hippo-memory 1.64.1 → 1.65.0

package/dist/db/request-stores.d.ts

@@ -0,0 +1,30 @@
+import type { DatabaseSyncLike } from './sqlite.js';
+export interface RequestStoresOptions {
+    /** Lock wait of every open in the scope that does not pass its own. */
+    readonly busyWaitMs?: number;
+    /** Set for hook scopes: after one lock wait runs out, {@link RequestStores.noteBusy} makes the scope's later writes skip at once. */
+    readonly failFastWhenBusy?: boolean;
+}
+/** The handles one request opened, keyed by resolved store path and lock wait. */
+export declare class RequestStores {
+    #private;
+    readonly busyWaitMs: number | undefined;
+    constructor(opts?: RequestStoresOptions);
+    get closed(): boolean;
+    /** The scope's handle on `hippoRoot`, opened on first use. `opts.busyWaitMs` overrides the scope's lock wait. */
+    get(hippoRoot: string, opts?: {
+        busyWaitMs?: number;
+    }): DatabaseSyncLike;
+    /** A lock held past one full wait belongs to a long transaction, so a hook scope's later writes skip at once. */
+    noteBusy(): void;
+    close(): void;
+}
+/** Runs `fn` in a request scope whose handles close when `fn` settles; inside an open scope `fn` joins it and `opts` is ignored. */
+export declare function runWithRequestStores<T>(fn: () => T | Promise<T>, opts?: RequestStoresOptions): Promise<T>;
+/** The scope this code runs in, if any. A closed scope still answers: its `get` falls through to a plain open. */
+export declare function currentRequestStores(): RequestStores | undefined;
+/** Runs `fn` outside every scope, for a connection that must outlive the request that happens to open it. */
+export declare function outsideRequestStores<T>(fn: () => T): T;
+/** Whether a scope owns `db` and will close it itself. */
+export declare function isScopedHandle(db: DatabaseSyncLike): boolean;
+//# sourceMappingURL=request-stores.d.ts.map

package/dist/db/request-stores.js

@@ -0,0 +1,100 @@
+// One store handle per store for each request (HTTP call, MCP tool call, scoped CLI command), opened lazily and closed with it.
+import * as path from 'node:path';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { connectHippoDb, getHippoDbPath } from './connect.js';
+// Handles a scope owns, so closeHippoDb leaves them open for the rest of the request.
+const scopedHandles = new WeakSet();
+// process.exit skips every finally, so one exit listener closes the handles of scopes still open.
+const liveScopes = new Set();
+let exitListenerInstalled = false;
+function closeLiveScopes() {
+    for (const scope of liveScopes)
+        scope.close();
+}
+function trackLive(scope) {
+    liveScopes.add(scope);
+    if (exitListenerInstalled)
+        return;
+    process.on('exit', closeLiveScopes);
+    exitListenerInstalled = true;
+}
+/** The handles one request opened, keyed by resolved store path and lock wait. */
+export class RequestStores {
+    busyWaitMs;
+    #failFastWhenBusy;
+    #handles = new Map();
+    #closed = false;
+    constructor(opts = {}) {
+        this.busyWaitMs = opts.busyWaitMs;
+        this.#failFastWhenBusy = opts.failFastWhenBusy === true;
+    }
+    get closed() {
+        return this.#closed;
+    }
+    /** The scope's handle on `hippoRoot`, opened on first use. `opts.busyWaitMs` overrides the scope's lock wait. */
+    get(hippoRoot, opts) {
+        const busyWaitMs = opts?.busyWaitMs ?? this.busyWaitMs;
+        // A listener or timer that outlives its request still sees this scope, so it gets a connection of its own.
+        if (this.#closed)
+            return connectHippoDb(hippoRoot, busyWaitMs);
+        const key = `${path.resolve(getHippoDbPath(hippoRoot))}\0${busyWaitMs ?? ''}`;
+        const cached = this.#handles.get(key);
+        if (cached?.isOpen && !cached.isTransaction)
+            return cached;
+        const db = connectHippoDb(hippoRoot, busyWaitMs);
+        // An open nested inside a transaction gets its own connection, which its caller closes.
+        if (cached?.isOpen)
+            return db;
+        this.#handles.set(key, db);
+        scopedHandles.add(db);
+        trackLive(this);
+        return db;
+    }
+    /** A lock held past one full wait belongs to a long transaction, so a hook scope's later writes skip at once. */
+    noteBusy() {
+        if (!this.#failFastWhenBusy)
+            return;
+        for (const db of this.#handles.values()) {
+            if (db.isOpen !== false)
+                db.exec('PRAGMA busy_timeout = 0');
+        }
+    }
+    close() {
+        this.#closed = true;
+        liveScopes.delete(this);
+        for (const db of this.#handles.values()) {
+            if (db.isOpen !== false)
+                db.close();
+        }
+        this.#handles.clear();
+    }
+}
+const scopes = new AsyncLocalStorage();
+/** Runs `fn` in a request scope whose handles close when `fn` settles; inside an open scope `fn` joins it and `opts` is ignored. */
+export async function runWithRequestStores(fn, opts) {
+    const outer = scopes.getStore();
+    if (outer && !outer.closed)
+        return fn();
+    const stores = new RequestStores(opts);
+    return scopes.run(stores, async () => {
+        try {
+            return await fn();
+        }
+        finally {
+            stores.close();
+        }
+    });
+}
+/** The scope this code runs in, if any. A closed scope still answers: its `get` falls through to a plain open. */
+export function currentRequestStores() {
+    return scopes.getStore();
+}
+/** Runs `fn` outside every scope, for a connection that must outlive the request that happens to open it. */
+export function outsideRequestStores(fn) {
+    return scopes.exit(fn);
+}
+/** Whether a scope owns `db` and will close it itself. */
+export function isScopedHandle(db) {
+    return scopedHandles.has(db);
+}
+//# sourceMappingURL=request-stores.js.map

package/dist/db/sqlite-blocked.d.ts

@@ -0,0 +1,6 @@
+/** Thrown by a hippo.db open inside a request served from another store: the code path is not ported to the store port yet. */
+export declare class SqliteBlockedError extends Error {
+    readonly storeKind: string;
+    constructor(storeKind: string);
+}
+//# sourceMappingURL=sqlite-blocked.d.ts.map

package/dist/db/sqlite-blocked.js

@@ -0,0 +1,11 @@
+// A leaf module, so http-util can map this error to a 501 without importing db/open, whose migrations reach back to http-util.
+/** Thrown by a hippo.db open inside a request served from another store: the code path is not ported to the store port yet. */
+export class SqliteBlockedError extends Error {
+    storeKind;
+    constructor(storeKind) {
+        super(`hippo.db is not opened while the '${storeKind}' store serves this request; this code path is not ported to the store yet`);
+        this.storeKind = storeKind;
+        this.name = 'SqliteBlockedError';
+    }
+}
+//# sourceMappingURL=sqlite-blocked.js.map

package/dist/db.d.ts

@@ -3,5 +3,7 @@ export { isSqliteBusy, isStoreBusy, StoreBusyError, STORE_BUSY_MESSAGE, execWith
 export { getSchemaVersion, getMeta, setMeta, isFtsAvailable } from './db/meta.js';
 export { countTableRows, pruneConsolidationRuns } from './db/tables.js';
 export { getCurrentSchemaVersion, IncompatibleBinaryError, ftsRowCounts, repairFtsDrift } from './db/migrate.js';
-export { getHippoDbPath, HOOK_DB_WAIT_MS, noteStoreBusy, withSharedStoreHandles, SERVER_DB_WAIT_MS, SLEEP_DB_WAIT_MS, withBusyWait, scopedBusyWait, SqliteBlockedError, withSqliteBlocked, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './db/open.js';
+export { getHippoDbPath, HOOK_DB_WAIT_MS, noteStoreBusy, withSharedStoreHandles, SERVER_DB_WAIT_MS, SLEEP_DB_WAIT_MS, scopedBusyWait, withSqliteBlocked, withSqliteAllowed, rethrowIfSqliteBlocked, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './db/open.js';
+export { RequestStores, runWithRequestStores, currentRequestStores, outsideRequestStores } from './db/request-stores.js';
+export { SqliteBlockedError } from './db/sqlite-blocked.js';
 //# sourceMappingURL=db.d.ts.map

package/dist/db.js

@@ -2,5 +2,7 @@ export { isSqliteBusy, isStoreBusy, StoreBusyError, STORE_BUSY_MESSAGE, execWith
 export { getSchemaVersion, getMeta, setMeta, isFtsAvailable } from './db/meta.js';
 export { countTableRows, pruneConsolidationRuns } from './db/tables.js';
 export { getCurrentSchemaVersion, IncompatibleBinaryError, ftsRowCounts, repairFtsDrift } from './db/migrate.js';
-export { getHippoDbPath, HOOK_DB_WAIT_MS, noteStoreBusy, withSharedStoreHandles, SERVER_DB_WAIT_MS, SLEEP_DB_WAIT_MS, withBusyWait, scopedBusyWait, SqliteBlockedError, withSqliteBlocked, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './db/open.js';
+export { getHippoDbPath, HOOK_DB_WAIT_MS, noteStoreBusy, withSharedStoreHandles, SERVER_DB_WAIT_MS, SLEEP_DB_WAIT_MS, scopedBusyWait, withSqliteBlocked, withSqliteAllowed, rethrowIfSqliteBlocked, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './db/open.js';
+export { RequestStores, runWithRequestStores, currentRequestStores, outsideRequestStores } from './db/request-stores.js';
+export { SqliteBlockedError } from './db/sqlite-blocked.js';
 //# sourceMappingURL=db.js.map

package/dist/embeddings.js

@@ -8,7 +8,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { randomUUID } from 'crypto';
 import { loadAllEntries } from './store/entry-reads.js';
-import { openHippoDb, closeHippoDb, getMeta, setMeta } from './db.js';
+import { openHippoDb, closeHippoDb, getMeta, rethrowIfSqliteBlocked, setMeta } from './db.js';
 import { EMBEDDING_MODEL_META_KEY, deleteOrphanVectors, hasStoredVectors, loadVectors, replaceAllVectors, storedVectorIds, upsertVectors, } from './vector-store.js';
 import { initializeParticle, savePhysicsState, loadPhysicsState, resetAllPhysicsState } from './physics-state.js';
 import { loadConfig } from './config.js';
@@ -81,6 +81,7 @@ function loadStoredEmbeddingModel(hippoRoot) {
         }
     }
     catch (err) {
+        rethrowIfSqliteBlocked(err);
         log.debug(`stored embedding model unreadable: ${err instanceof Error ? err.message : String(err)}`);
         return null;
     }

package/dist/goals.d.ts

@@ -78,6 +78,13 @@ export interface GetActiveGoalsOpts {
     tenantId: string;
 }
 export declare function getActiveGoals(hippoRoot: string, opts: GetActiveGoalsOpts): Goal[];
+/** A session's active goals, oldest first, and the retrieval policy of each goal that names one. */
+export interface ActiveGoals {
+    readonly goals: Goal[];
+    readonly policies: ReadonlyMap<string, RetrievalPolicy>;
+}
+/** The active goals and their policies on one handle, so a goal and its policy never disagree. */
+export declare function activeGoalsWithPolicies(hippoRoot: string, opts: GetActiveGoalsOpts): ActiveGoals;
 /** Every goal of a (tenant, session), whatever its status, oldest first. */
 export declare function getSessionGoals(hippoRoot: string, opts: GetActiveGoalsOpts): Goal[];
 export declare function getActiveGoalsWithDb(db: DatabaseSyncLike, opts: GetActiveGoalsOpts): Goal[];
@@ -90,7 +97,7 @@ export interface GoalRecallLogRow {
     recalledAt: string;
     score: number;
 }
-/** Options shared by {@link computeGoalStackBoost} and {@link applyGoalStackBoost}. */
+/** Options shared by {@link computeGoalStackBoost} and {@link boostByGoals}. */
 export interface GoalStackBoostOpts {
     sessionId: string;
     tenantId: string;
@@ -107,6 +114,10 @@ export interface GoalStackBoost<R> {
     results: R[];
     log: GoalRecallLogRow[];
 }
+export declare function loadGoalPolicies(db: DatabaseSyncLike, active: readonly Goal[]): Map<string, RetrievalPolicy>;
+/** The rows whose memory lives in this store: goal_recall_log.memory_id references memories, so a global row would fail
+ *  the insert. A global result keeps its boost; it only earns no log row, so no outcome propagation. */
+export declare function localGoalRecallRows(db: DatabaseSyncLike, rows: readonly GoalRecallLogRow[]): GoalRecallLogRow[];
 /**
  * dlPFC goal-stack boost. Applies the multi-goal boost to entry-backed scored
  * rows when (tenant, session) has active goals and returns the log rows to
@@ -130,21 +141,17 @@ export declare function computeGoalStackBoost<R extends {
     entry: MemoryEntry;
     score: number;
 }>(db: DatabaseSyncLike, results: R[], opts: GoalStackBoostOpts): GoalStackBoost<R>;
+/** {@link computeGoalStackBoost} over goals already read, touching no store. Its log keeps rows whose memory is global,
+ *  since only the store can tell them apart; {@link localGoalRecallRows} drops those before the write. */
+export declare function boostByGoals<R extends {
+    entry: MemoryEntry;
+    score: number;
+}>(results: R[], active: ActiveGoals, opts: GoalStackBoostOpts): GoalStackBoost<R>;
 /**
  * Writes goal-boost log rows. INSERT OR IGNORE because UNIQUE(memory_id, goal_id)
  * makes a re-recall during the same goal life a no-op for outcome attribution.
  */
 export declare function writeGoalRecallLog(db: DatabaseSyncLike, rows: readonly GoalRecallLogRow[]): void;
-/**
- * {@link computeGoalStackBoost} plus {@link writeGoalRecallLog} in one call, for
- * pipelines that boost and log on the same handle.
- *
- * @internal Recall ranking helper. Subject to change.
- */
-export declare function applyGoalStackBoost<R extends {
-    entry: MemoryEntry;
-    score: number;
-}>(db: DatabaseSyncLike, results: R[], opts: GoalStackBoostOpts): R[];
 export interface CompleteGoalOpts {
     outcomeScore?: number;
     /**

package/dist/goals.js

@@ -129,6 +129,17 @@ export function getActiveGoals(hippoRoot, opts) {
         closeHippoDb(db);
     }
 }
+/** The active goals and their policies on one handle, so a goal and its policy never disagree. */
+export function activeGoalsWithPolicies(hippoRoot, opts) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        const goals = getActiveGoalsWithDb(db, opts);
+        return { goals, policies: loadGoalPolicies(db, goals) };
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 /** Every goal of a (tenant, session), whatever its status, oldest first. */
 export function getSessionGoals(hippoRoot, opts) {
     const db = openHippoDb(hippoRoot);
@@ -163,7 +174,7 @@ export function getActiveGoalsWithDb(db, opts) {
 // can compose onto the base goal-tag boost. Composed result is hard-capped
 // at MAX_FINAL_MULTIPLIER (3.0x) BEFORE applying to score -- even an
 // `errorPriority: 9.0` policy cannot exceed 3.0x.
-function loadGoalPolicies(db, active) {
+export function loadGoalPolicies(db, active) {
     const policiesByGoalId = new Map();
     for (const g of active) {
         if (!g.retrievalPolicyId)
@@ -220,28 +231,11 @@ function goalBoostMultiplier(entry, tags, matches, goalsByTag, policiesByGoalId)
     return Math.min(multiplier, MAX_FINAL_MULTIPLIER);
 }
 /** Log rows for the top `limit` boosted rows, one per matched goal. */
-function buildGoalRecallLog(db, boosted, matchesByEntryId, goalsByTag, opts) {
+function buildGoalRecallLog(boosted, matchesByEntryId, goalsByTag, opts) {
     const { sessionId, tenantId, limit } = opts;
-    // Filter to local memories only -- global memory IDs aren't in this DB's
-    // memories table, so the FK on goal_recall_log.memory_id would fail.
-    // dlPFC depth's outcome propagation is session-scoped to local; boost on
-    // ranking still applies to global results, just no log row -> no
-    // propagation.
-    const topKIds = boosted.slice(0, limit).map((r) => r.entry.id);
-    const localIds = new Set();
-    if (topKIds.length > 0) {
-        const placeholders = topKIds.map(() => '?').join(',');
-        // SAFETY: rows come from the SELECT above, which projects exactly one
-        // column, `id`, from memories.
-        const localRows = db.prepare(`SELECT id FROM memories WHERE id IN (${placeholders})`).all(...topKIds);
-        for (const row of localRows)
-            localIds.add(row.id);
-    }
     const recalledAt = new Date().toISOString();
     const log = [];
     for (const r of boosted.slice(0, limit)) {
-        if (!localIds.has(r.entry.id))
-            continue; // global -> skip log insert
         const matches = matchesByEntryId.get(r.entry.id);
         if (!matches || matches.length === 0)
             continue;
@@ -254,6 +248,17 @@ function buildGoalRecallLog(db, boosted, matchesByEntryId, goalsByTag, opts) {
     }
     return log;
 }
+/** The rows whose memory lives in this store: goal_recall_log.memory_id references memories, so a global row would fail
+ *  the insert. A global result keeps its boost; it only earns no log row, so no outcome propagation. */
+export function localGoalRecallRows(db, rows) {
+    if (rows.length === 0)
+        return [];
+    const ids = [...new Set(rows.map((r) => r.memoryId))];
+    // SAFETY: the SELECT projects exactly one column, `id`, from memories.
+    const local = db.prepare(`SELECT id FROM memories WHERE id IN (${ids.map(() => '?').join(',')})`).all(...ids);
+    const localIds = new Set(local.map((r) => r.id));
+    return rows.filter((r) => localIds.has(r.memoryId));
+}
 /**
  * dlPFC goal-stack boost. Applies the multi-goal boost to entry-backed scored
  * rows when (tenant, session) has active goals and returns the log rows to
@@ -274,12 +279,20 @@ function buildGoalRecallLog(db, boosted, matchesByEntryId, goalsByTag, opts) {
  * @internal Recall ranking helper. Subject to change.
  */
 export function computeGoalStackBoost(db, results, opts) {
-    const { sessionId, tenantId, trace } = opts;
-    const active = getActiveGoalsWithDb(db, { sessionId, tenantId });
-    if (active.length === 0)
+    const goals = getActiveGoalsWithDb(db, { sessionId: opts.sessionId, tenantId: opts.tenantId });
+    if (goals.length === 0)
+        return { results, log: [] };
+    const boost = boostByGoals(results, { goals, policies: loadGoalPolicies(db, goals) }, opts);
+    return { results: boost.results, log: localGoalRecallRows(db, boost.log) };
+}
+/** {@link computeGoalStackBoost} over goals already read, touching no store. Its log keeps rows whose memory is global,
+ *  since only the store can tell them apart; {@link localGoalRecallRows} drops those before the write. */
+export function boostByGoals(results, active, opts) {
+    const { trace } = opts;
+    if (active.goals.length === 0)
         return { results, log: [] };
-    const goalsByTag = new Map(active.map((g) => [g.goalName, g]));
-    const policiesByGoalId = loadGoalPolicies(db, active);
+    const goalsByTag = new Map(active.goals.map((g) => [g.goalName, g]));
+    const policiesByGoalId = active.policies;
     // Goal-tag matches per boosted row, keyed by entry id. Kept as a side table
     // (rather than a spread-on `_goalMatches` marker property) so `boosted`
     // stays exactly R[] end to end, with no cast-tag-then-strip round trip.
@@ -313,7 +326,7 @@ export function computeGoalStackBoost(db, results, opts) {
         // inherits its determinism via sort stability, and ties preserve the
         // prior (meaningful) rank instead of reordering by content.
         .sort((a, b) => b.score - a.score);
-    return { results: boosted, log: buildGoalRecallLog(db, boosted, matchesByEntryId, goalsByTag, opts) };
+    return { results: boosted, log: buildGoalRecallLog(boosted, matchesByEntryId, goalsByTag, opts) };
 }
 /**
  * Writes goal-boost log rows. INSERT OR IGNORE because UNIQUE(memory_id, goal_id)
@@ -331,17 +344,6 @@ export function writeGoalRecallLog(db, rows) {
         insertLog.run(row.goalId, row.memoryId, row.tenantId, row.sessionId, row.recalledAt, row.score);
     }
 }
-/**
- * {@link computeGoalStackBoost} plus {@link writeGoalRecallLog} in one call, for
- * pipelines that boost and log on the same handle.
- *
- * @internal Recall ranking helper. Subject to change.
- */
-export function applyGoalStackBoost(db, results, opts) {
-    const boost = computeGoalStackBoost(db, results, opts);
-    writeGoalRecallLog(db, boost.log);
-    return boost.results;
-}
 const POSITIVE_OUTCOME_THRESHOLD = 0.7;
 const NEGATIVE_OUTCOME_THRESHOLD = 0.3;
 const STRENGTH_BOOST = 1.10;

package/dist/http-util.d.ts

@@ -23,6 +23,8 @@ export interface ApiErrorReply {
     message: string;
 }
 export declare const INTERNAL_ERROR_MESSAGE = "internal server error";
+/** The reply when a request under another store reaches code that still opens hippo.db. */
+export declare const STORE_NOT_PORTED_MESSAGE = "store_not_ported";
 /** Maps by class so rewording a message never moves a status; an untyped error is a 500 whose text stays in the server log. */
 export declare function mapApiError<E>(err: E): ApiErrorReply;
 /** Serialises before the head goes out, so a body that is not JSON still reaches the caller's error reply. */

package/dist/http-util.js

@@ -1,4 +1,5 @@
 import { ApiError } from './api-errors.js';
+import { SqliteBlockedError } from './db/sqlite-blocked.js';
 // Leaf module shared by server.ts and the connector webhook receivers; it must not import either.
 export function isJsonObjectRecord(value) {
     return value !== undefined && value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -35,6 +36,8 @@ export class BodyTooLargeError extends Error {
 export class BodyTimeoutError extends Error {
 }
 export const INTERNAL_ERROR_MESSAGE = 'internal server error';
+/** The reply when a request under another store reaches code that still opens hippo.db. */
+export const STORE_NOT_PORTED_MESSAGE = 'store_not_ported';
 /** Maps by class so rewording a message never moves a status; an untyped error is a 500 whose text stays in the server log. */
 export function mapApiError(err) {
     // An add-on can build an HttpError from any number, and writeHead throws on one outside 100-999.
@@ -47,6 +50,8 @@ export function mapApiError(err) {
         return { status: 413, message: err.message };
     if (err instanceof BodyTimeoutError)
         return { status: 408, message: err.message };
+    if (err instanceof SqliteBlockedError)
+        return { status: 501, message: STORE_NOT_PORTED_MESSAGE };
     return { status: 500, message: INTERNAL_ERROR_MESSAGE };
 }
 /** Serialises before the head goes out, so a body that is not JSON still reaches the caller's error reply. */

package/dist/mcp/memory-tools.js

@@ -3,6 +3,7 @@ import { log } from '../log.js';
 import { readEntry } from '../store/entry-reads.js';
 import { countCreatedSinceLastSleep } from '../store/index-and-stats.js';
 import { consolidate } from '../consolidate/sleep.js';
+import { outsideRequestStores, runWithRequestStores, scopedBusyWait } from '../db.js';
 import { resolveTenantId } from '../tenant.js';
 import { remember as apiRemember, outcome as apiOutcome, learn as apiLearn, MCP_LEARN } from '../api.js';
 import { mcpActor } from './protocol.js';
@@ -43,7 +44,9 @@ export function runRememberTool({ args, ctx, hippoRoot, config, tenantId }) {
         countCreatedSinceLastSleep(hippoRoot, tenantId) >= config.autoSleep.threshold) {
         autoSleepInFlight.add(hippoRoot);
         // Fire-and-forget (never block the response); an unhandled rejection would kill the server, so log it.
-        consolidate(hippoRoot)
+        // Its own scope: the call's closes a handle the sleep still holds across its pauses, but the caller's lock wait carries over.
+        const busyWaitMs = scopedBusyWait();
+        outsideRequestStores(() => runWithRequestStores(() => consolidate(hippoRoot), { busyWaitMs }))
             .catch((err) => {
             log.error(`auto-sleep consolidate failed (tenant ${tenantId}): ${err instanceof Error ? err.message : String(err)}`);
         })

package/dist/mcp/recall-tools.js

@@ -6,58 +6,18 @@ import { retrieve as apiRetrieve, drillDown as apiDrillDown, assemble as apiAsse
 import { autoDetectContext } from '../context-auto.js';
 import { resolveProjectIdentity } from '../project-identity.js';
 import { isSharedStore } from '../config.js';
-import { appendAuditEvent, auditQueryFields } from '../audit.js';
-import { detectAnchoring, hashQueryText, biasHintEnabled, buildSessionKey, getOrCreateRing, appendRecall, snapshotRing, } from '../recall-history.js';
+import { detectAnchoring, hashQueryText, biasHintEnabled, snapshotRing } from '../recall-history.js';
 import { detectAvailabilityBias } from '../availability.js';
-import { openHippoDb, closeHippoDb } from '../db.js';
 import { estimateTokens } from '../token-ledger.js';
 import { assembleCost, assembleText, drillCost, drillText } from '../context-render.js';
-import { mcpActor, isJsonBoolean } from './protocol.js';
-import { sessionRecallHistoryMcp, lastRecalledIds, resolveClientKey } from './session-state.js';
+import { mcpActor } from './protocol.js';
+import { lastRecalledIds, resolveClientKey } from './session-state.js';
 import { formatContinuityBlock, formatMemories, memoryCost, memoriesReserve, snapshotPiece, handoffPiece, trailPiece, contextCost, tailSection, planningSection, } from './format.js';
 import { isJsonString } from '../json.js';
-import { MAX_ID_LEN } from '../http-util.js';
-function parseRecallArgs(args, defaultBudget) {
-    const query = String(args.query || '');
-    const budget = Number(args.budget) || defaultBudget;
-    const includeContinuity = Boolean(args.include_continuity);
-    const explicitScope = isJsonString(args.scope) && args.scope.length > 0
-        ? args.scope
-        : undefined;
-    const freshTailCountArg = Number(args.fresh_tail_count);
-    const freshTailCount = Number.isFinite(freshTailCountArg) && freshTailCountArg > 0
-        ? freshTailCountArg
-        : undefined;
-    const freshTailSessionId = isJsonString(args.fresh_tail_session_id) && args.fresh_tail_session_id.length > 0
-        ? args.fresh_tail_session_id
-        : undefined;
-    const summarizeOverflow = isJsonBoolean(args.summarize_overflow)
-        ? args.summarize_overflow
-        : undefined;
-    // Number-coerce, never typeof-check: "abc" must reach api.retrieve and fail as invalid_scorer_window, the same code HTTP returns.
-    const scorerWindow = args.scorer_window === undefined
-        ? undefined
-        : Number(args.scorer_window);
-    // session_id drives the goal-stack boost inside api.retrieve; same trim and MAX_ID_LEN cap as fresh_tail_session_id.
-    const sessionIdRaw = isJsonString(args.session_id) ? args.session_id.trim() : '';
-    const sessionId = sessionIdRaw.length > 0 && sessionIdRaw.length <= MAX_ID_LEN
-        ? sessionIdRaw
-        : undefined;
-    const recallExtra = {};
-    if (freshTailCount !== undefined)
-        recallExtra.freshTailCount = freshTailCount;
-    if (freshTailSessionId !== undefined)
-        recallExtra.freshTailSessionId = freshTailSessionId;
-    if (summarizeOverflow !== undefined)
-        recallExtra.summarizeOverflow = summarizeOverflow;
-    if (scorerWindow !== undefined)
-        recallExtra.scorerWindow = scorerWindow;
-    if (sessionId !== undefined)
-        recallExtra.sessionId = sessionId;
-    return { query, budget, includeContinuity, explicitScope, sessionId, recallExtra };
-}
-/** Builds the showRanked callback that renders the list MCP shows and parks the render in `out`. */
-function recallPresenter(budget, includeContinuity, anchorRing, queryHash, out) {
+import { parseContextRequest, parseRecallRequest, toolParams } from '../api/recall-request.js';
+import { noteRecall, sessionRing, shownRecallRows } from '../api/recall-record.js';
+/** Builds the showRanked callback that renders the list MCP shows, parks the render in `out` and hands back its hint rows. */
+function recallPresenter(budget, includeContinuity, anchorRing, queryHash, out, hintRows) {
     return ({ ranked, pool, droppedByScope }, apiResult) => {
         // Sections are paid in print order, ahead of the memories and after the heading; one that does not fit is dropped whole.
         let left = budget - memoriesReserve(budget);
@@ -129,105 +89,46 @@ function recallPresenter(budget, includeContinuity, anchorRing, queryHash, out)
             rendered = render(results);
         }
         out.rendered = rendered;
-        return rendered.list.map((r) => r.entry.id);
+        return { ids: rendered.list.map((r) => r.entry.id), audit: hintRows(rendered) };
     };
 }
-function appendRecallAudit(hippoRoot, event) {
-    const dbForAudit = openHippoDb(hippoRoot);
-    try {
-        appendAuditEvent(dbForAudit, event);
-    }
-    finally {
-        closeHippoDb(dbForAudit);
-    }
-}
-function auditRecallHints(call, query, anchorRing, queryHash, rendered) {
-    const { hippoRoot, tenantId, ctx } = call;
-    const { anchoring: mcpAnchoringHint, availability: mcpAvailabilityHint, list: shown } = rendered;
-    if (biasHintEnabled('anchoring')) {
-        if (anchorRing) {
-            // Appended after the final detect: anchoredOn feeds the cooldown for the next recall on this session.
-            appendRecall(anchorRing, queryHash, shown[0]?.entry.id ?? null, mcpAnchoringHint?.memoryId);
-            if (mcpAnchoringHint?.reason === 'memory_dominance') {
-                appendRecallAudit(hippoRoot, {
-                    tenantId,
-                    actor: ctx?.actor ?? 'mcp',
-                    op: 'recall_anchor_detected_memory_dominance',
-                    targetId: mcpAnchoringHint.memoryId,
-                    metadata: {
-                        memory_id: mcpAnchoringHint.memoryId,
-                        query_count: mcpAnchoringHint.queryCount ?? null,
-                    },
-                });
-            }
-            else if (mcpAnchoringHint?.reason === 'query_repeat') {
-                appendRecallAudit(hippoRoot, {
-                    tenantId,
-                    actor: ctx?.actor ?? 'mcp',
-                    op: 'recall_anchor_detected_query_repeat',
-                    targetId: mcpAnchoringHint.memoryId,
-                    metadata: { memory_id: mcpAnchoringHint.memoryId },
-                });
-            }
-        }
-        else {
-            // No sessionId, so no ring. Hash the prompt with SHA-256/16 as the recall audit does (api.ts:854):
-            // hashQueryText is FNV-1a 32-bit, trivial to brute-force on low-entropy queries.
-            appendRecallAudit(hippoRoot, {
-                tenantId,
-                actor: ctx?.actor ?? 'mcp',
-                op: 'recall_anchor_skipped_no_session',
-                targetId: undefined,
-                metadata: auditQueryFields(query),
-            });
-        }
-    }
-    if (mcpAvailabilityHint) {
-        appendRecallAudit(hippoRoot, {
-            tenantId,
-            actor: ctx?.actor ?? 'mcp',
-            op: 'recall_availability_detected',
-            metadata: {
-                recent_fraction: mcpAvailabilityHint.recentFraction,
-                older_passed_over: mcpAvailabilityHint.olderCandidatesPassedOver,
-                returned_count: mcpAvailabilityHint.returnedCount,
-            },
-        });
-    }
-}
 export async function runRecallTool(call) {
-    const { ctx, hippoRoot, config, tenantId } = call;
-    const { query, budget, includeContinuity, explicitScope, sessionId, recallExtra } = parseRecallArgs(call.args, config.defaultBudget);
+    const { ctx, hippoRoot, config, tenantId, args } = call;
+    // MCP keeps its own band size and search mode, so limit, mode and explain are checked but not passed on.
+    const { opts: recallOpts } = parseRecallRequest(toolParams(args));
+    const { query, includeContinuity, sessionId } = recallOpts;
+    const budget = Number(args.budget) || config.defaultBudget;
     const apiCtx = {
         hippoRoot,
         tenantId,
         actor: mcpActor(ctx),
         store: ctx?.store,
     };
-    const anchorRing = biasHintEnabled('anchoring') && sessionId
-        ? getOrCreateRing(sessionRecallHistoryMcp, buildSessionKey(tenantId, sessionId))
-        : null;
+    const anchorRing = sessionRing('mcp', tenantId, sessionId);
+    const who = { tenantId, actor: ctx?.actor ?? 'mcp' };
     const queryHash = hashQueryText(query);
     const out = {};
     // RecallContractError throws reach the MCP caller raw, as mcp-recall-fresh-tail-policy.test.ts pins.
     await apiRetrieve(apiCtx, {
-        query,
+        ...recallOpts,
         limit: 50,
-        scope: explicitScope,
-        includeContinuity,
         mode: config.physics?.enabled !== false ? 'physics' : 'hybrid',
         // The hint is computed below over the list MCP shows; the window band's copy would emit its audit row twice.
         suppressAvailabilityHint: true,
         keepHeldCopies: true,
         project: ctx?.project,
-        ...recallExtra,
-        showRanked: recallPresenter(budget, includeContinuity, anchorRing, queryHash, out),
+        showRanked: recallPresenter(budget, includeContinuity, anchorRing, queryHash, out, ({ list, anchoring, availability }) => shownRecallRows(who, {
+            query, ring: anchorRing, topId: list[0]?.entry.id ?? null, anchoring, availability,
+        })),
     });
-    if (!out.rendered)
+    const { rendered } = out;
+    if (!rendered)
         throw new Error('hippo_recall: api.retrieve returned without calling showRanked');
-    lastRecalledIds.set(resolveClientKey(ctx), out.rendered.list.map((r) => r.entry.id));
-    auditRecallHints(call, query, anchorRing, queryHash, out.rendered);
-    return out.rendered.text;
+    lastRecalledIds.set(resolveClientKey(ctx), rendered.list.map((r) => r.entry.id));
+    // Fed once the recall's rows are written, after the final detect: anchoredOn feeds the cooldown for the next recall on this session.
+    if (anchorRing)
+        noteRecall(anchorRing, query, rendered.list[0]?.entry.id ?? null, rendered.anchoring?.memoryId);
+    return rendered.text;
 }
 export function runAssembleTool({ args, ctx, hippoRoot, tenantId }) {
     const sessionId = String(args.session_id || '');
@@ -301,18 +202,12 @@ export async function runContextTool({ args, ctx, hippoRoot, config, tenantId })
     // Stdio names no project, and the store's folder or the launch cwd is no caller's; HTTP sends X-Hippo-Project.
     if (isSharedStore(hippoRoot) && ctx?.project === undefined)
         return 'hippo_context needs a project on a shared store; use hippo_recall';
-    const budget = args.budget === undefined
-        ? config.defaultContextBudget
-        : Number(args.budget);
-    if (!Number.isFinite(budget) || budget < 0)
-        return 'budget must be a non-negative number.';
+    const { budget: budgetArg, scope: exactScope } = parseContextRequest(toolParams(args));
+    const budget = budgetArg ?? config.defaultContextBudget;
     if (budget === 0)
         return '';
     if (budget < memoriesReserve(budget))
         return ''; // not even the heading fits, so nothing prints, as at budget 0
-    const exactScope = isJsonString(args.scope) && args.scope.length > 0
-        ? args.scope
-        : undefined;
     const result = await apiGetContext({ hippoRoot, tenantId, actor: mcpActor(ctx), store: ctx?.store }, {
         // The server's git state is no caller's, so a shared-store caller gets its project's rows without a query.
         q: ctx?.project ? undefined : autoDetectContext(),