hippo-memory 1.64.0 → 1.65.0

package/dist/local-embedding.js

@@ -10,6 +10,7 @@ let _embeddingAvailable = null;
 // A pipeline is expensive to load, so one instance per model is kept for the process.
 const _pipelineInstances = new Map();
 const _pipelineLoading = new Map();
+const _pipelineErrors = new Map();
 export const DEFAULT_EMBEDDING_MODEL = 'Xenova/all-MiniLM-L6-v2';
 /** BGE was trained with CLS pooling; everything else gets mean, the sentence-transformers default, since CLS degrades mean-trained models. */
 export function poolingFor(model) {
@@ -79,8 +80,10 @@ async function loadPipeline(model) {
     const loading = (async () => {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const pkg = resolveTransformersPackage();
-        if (!pkg)
+        if (!pkg) {
+            _pipelineErrors.set(model, 'no transformers package is installed');
             return null;
+        }
         let pipelineFn = null;
         try {
             // SAFETY: the resolved module's shape is untyped by design (optional peer
@@ -98,11 +101,16 @@ async function loadPipeline(model) {
             pipelineFn = mod.pipeline ?? mod.default?.pipeline;
         }
         catch (err) {
-            log.debug(`transformers import failed (${pkg}): ${err instanceof Error ? err.message : String(err)}`);
+            // String(err) keeps a Node error's [ERR_...] code, which callers match on.
+            const reason = `transformers import failed (${pkg}): ${String(err)}`;
+            log.debug(reason);
+            _pipelineErrors.set(model, reason);
             return null;
         }
-        if (!pipelineFn)
+        if (!pipelineFn) {
+            _pipelineErrors.set(model, `${pkg} exports no pipeline function`);
             return null;
+        }
         // The offline bundle used in egress-blocked sandboxes ships only the FP32 model, so use whichever file is on disk.
         const cacheRoot = envModelCache();
         const quantized = !cacheRoot
@@ -113,7 +121,9 @@ async function loadPipeline(model) {
             return instance;
         }
         catch (err) {
-            log.debug(`embedding pipeline load failed (${model}): ${err instanceof Error ? err.message : String(err)}`);
+            const reason = `embedding pipeline load failed (${model}): ${String(err)}`;
+            log.debug(reason);
+            _pipelineErrors.set(model, reason);
             return null;
         }
         finally {
@@ -123,6 +133,12 @@ async function loadPipeline(model) {
     _pipelineLoading.set(model, loading);
     return loading;
 }
+/** Throws, with the reason, when the model's pipeline cannot load: a provider-level failure, not a per-item skip. */
+export async function requireLocalPipeline(model) {
+    if (await loadPipeline(model))
+        return;
+    throw new Error(`local embedding model did not load: ${_pipelineErrors.get(model) ?? 'unknown reason'}`);
+}
 export function resolveEmbeddingModel(hippoRoot, explicitModel) {
     const direct = explicitModel?.trim();
     if (direct)

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(),

package/dist/mcp/request.d.ts

@@ -1,4 +1,11 @@
 import { type McpContext, type McpRequest, type McpResponse } from './protocol.js';
+/**
+ * Record the memory text a recall or context tool returned. Best-effort: a
+ * ledger failure never fails the tool call. Other tools are not recorded.
+ */
+export declare function recordMcpTokens(toolName: string, output: string, ctx?: McpContext): Promise<void>;
+/** The tools listed and run under a store other than hippo.db. */
+export declare const STORE_READY_TOOLS: ReadonlySet<string>;
 /**
  * Transport-agnostic MCP dispatcher. Both the stdio loop (below) and the
  * HTTP/SSE transport in src/server.ts route every incoming JSON-RPC message

package/dist/mcp/request.js

@@ -1,12 +1,15 @@
 // Transport-agnostic request handling: tool dispatch table, tool execution and the JSON-RPC method switch.
 import { log } from '../log.js';
+import { STORE_NOT_PORTED_MESSAGE } from '../http-util.js';
 import { getGlobalRoot, initGlobal } from '../shared.js';
 import { loadConfig } from '../config.js';
 import { resolveTenantId } from '../tenant.js';
-import { openHippoDb, closeHippoDb } from '../db.js';
-import { estimateTokens, recordTokenUse } from '../token-ledger.js';
+import { rethrowIfSqliteBlocked, runWithRequestStores } from '../db.js';
+import { storeFor } from '../store-port.js';
+import { estimateTokens } from '../token-ledger.js';
 import { PACKAGE_VERSION } from '../version.js';
 import { validateToolArgs } from './tool-args.js';
+import { RecallRequestError } from '../api/recall-request.js';
 import { findHippoRoot, isJsonObjectRecord } from './protocol.js';
 import { TOOLS, TOOLS_BY_NAME, ARGS_CHECKED_BY_API } from './tools.js';
 import { runRecallTool, runAssembleTool, runDrillTool, runContextTool } from './recall-tools.js';
@@ -35,7 +38,7 @@ const MCP_TOKEN_SURFACES = new Map([
  * Record the memory text a recall or context tool returned. Best-effort: a
  * ledger failure never fails the tool call. Other tools are not recorded.
  */
-function recordMcpTokens(toolName, output, ctx) {
+export async function recordMcpTokens(toolName, output, ctx) {
     const surface = MCP_TOKEN_SURFACES.get(toolName);
     if (!surface || !output)
         return;
@@ -43,40 +46,41 @@ function recordMcpTokens(toolName, output, ctx) {
         const hippoRoot = ctx?.hippoRoot ?? findHippoRoot();
         if (!hippoRoot)
             return;
-        const db = openHippoDb(hippoRoot);
-        try {
-            recordTokenUse(db, {
-                tenantId: ctx?.tenantId ?? resolveTenantId({}),
-                surface,
-                event: 'inject',
-                items: 0,
-                tokens: estimateTokens(output),
-            });
-        }
-        finally {
-            closeHippoDb(db);
-        }
+        await storeFor({ hippoRoot, store: ctx?.store }).recordTokens({
+            tenantId: ctx?.tenantId ?? resolveTenantId({}),
+            surface,
+            event: 'inject',
+            items: 0,
+            tokens: estimateTokens(output),
+        });
     }
     catch (err) {
+        rethrowIfSqliteBlocked(err);
         log.warnThenDebug('mcp-token-ledger', `token ledger write failed; the tool reply is unaffected: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
-// ── Tool execution ──
 const TOOL_HANDLERS = new Map([
-    ['hippo_recall', runRecallTool],
-    ['hippo_assemble', runAssembleTool],
-    ['hippo_drill', runDrillTool],
-    ['hippo_predict_baserate', runPredictBaserateTool],
-    ['hippo_remember', runRememberTool],
-    ['hippo_outcome', runOutcomeTool],
-    ['hippo_context', runContextTool],
-    ['hippo_status', runStatusTool],
-    ['hippo_learn', runLearnTool],
-    ['hippo_conflicts', runConflictsTool],
-    ['hippo_resolve', runResolveTool],
-    ['hippo_share', runShareTool],
-    ['hippo_peers', runPeersTool],
+    ['hippo_recall', { handler: runRecallTool, storeReady: true }],
+    ['hippo_assemble', { handler: runAssembleTool }],
+    ['hippo_drill', { handler: runDrillTool }],
+    ['hippo_predict_baserate', { handler: runPredictBaserateTool }],
+    ['hippo_remember', { handler: runRememberTool }],
+    ['hippo_outcome', { handler: runOutcomeTool }],
+    ['hippo_context', { handler: runContextTool }],
+    ['hippo_status', { handler: runStatusTool }],
+    ['hippo_learn', { handler: runLearnTool }],
+    ['hippo_conflicts', { handler: runConflictsTool }],
+    ['hippo_resolve', { handler: runResolveTool }],
+    ['hippo_share', { handler: runShareTool }],
+    ['hippo_peers', { handler: runPeersTool }],
 ]);
+/** The tools listed and run under a store other than hippo.db. */
+export const STORE_READY_TOOLS = new Set([...TOOL_HANDLERS].filter(([, entry]) => entry.storeReady).map(([name]) => name));
+/** The served store's kind when it is not hippo.db, else null. */
+function otherStoreKind(ctx) {
+    const kind = ctx?.store?.kind;
+    return kind !== undefined && kind !== 'sqlite' ? kind : null;
+}
 async function executeTool(name, args, ctx) {
     // When a transport hands us a context (HTTP path), trust it: the HTTP
     // server already resolved hippoRoot from its bound opts and tenantId
@@ -89,13 +93,21 @@ async function executeTool(name, args, ctx) {
     // tenant-isolated. Resolved once per tool call: prefer the transport's
     // ctx.tenantId so an HTTP Bearer for tenant B doesn't drop to HIPPO_TENANT.
     const tenantId = ctx?.tenantId ?? resolveTenantId({});
-    const handler = TOOL_HANDLERS.get(name);
+    const handler = TOOL_HANDLERS.get(name)?.handler;
     // handleMcpRequest rejects names missing from TOOLS, so reaching here means TOOLS and this table drifted apart.
     if (!handler)
         throw new Error(`hippo-mcp: tool ${name} is declared but has no handler`);
     return handler({ args, ctx, hippoRoot, config, tenantId });
 }
 // ── Request handling ──
+// The MCP spec reports input validation as a tool result with isError, so the model can read it and retry.
+function invalidArgs(id, toolName, problems) {
+    return {
+        jsonrpc: '2.0',
+        id,
+        result: { content: [{ type: 'text', text: `Invalid arguments for ${toolName}: ${problems.join('; ')}` }], isError: true },
+    };
+}
 /**
  * Transport-agnostic MCP dispatcher. Both the stdio loop (below) and the
  * HTTP/SSE transport in src/server.ts route every incoming JSON-RPC message
@@ -119,7 +131,7 @@ export async function handleMcpRequest(req, ctx) {
         case 'notifications/initialized':
             return null;
         case 'tools/list':
-            return { jsonrpc: '2.0', id, result: { tools: TOOLS } };
+            return { jsonrpc: '2.0', id, result: { tools: otherStoreKind(ctx) ? TOOLS.filter((t) => STORE_READY_TOOLS.has(t.name)) : TOOLS } };
         case 'tools/call': {
             const nameValue = params?.name;
             const toolName = isJsonString(nameValue) ? nameValue : '';
@@ -127,6 +139,10 @@ export async function handleMcpRequest(req, ctx) {
             if (!tool) {
                 return { jsonrpc: '2.0', id, error: { code: -32602, message: `Unknown tool: ${toolName.slice(0, 128)}` } };
             }
+            // The same refusal a ported tool gives when it reaches hippo.db, so a client handles one shape.
+            if (otherStoreKind(ctx) && !STORE_READY_TOOLS.has(toolName)) {
+                return { jsonrpc: '2.0', id, error: { code: -32603, message: STORE_NOT_PORTED_MESSAGE } };
+            }
             const refusal = sharedStoreRefusal(toolName, ctx);
             if (refusal !== undefined)
                 return { jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: refusal }], isError: true } };
@@ -135,17 +151,23 @@ export async function handleMcpRequest(req, ctx) {
                 return { jsonrpc: '2.0', id, error: { code: -32602, message: `${toolName}: arguments must be an object` } };
             }
             const toolArgs = isJsonObjectRecord(argumentsValue) ? argumentsValue : {};
-            // The MCP spec reports input validation as a tool result with isError, so the model can read it and retry.
             const problems = validateToolArgs(tool.inputSchema, toolArgs, ARGS_CHECKED_BY_API.get(toolName));
-            if (problems.length > 0) {
-                return {
-                    jsonrpc: '2.0',
-                    id,
-                    result: { content: [{ type: 'text', text: `Invalid arguments for ${toolName}: ${problems.join('; ')}` }], isError: true },
-                };
+            if (problems.length > 0)
+                return invalidArgs(id, toolName, problems);
+            let output;
+            try {
+                // One handle per store for the tool and its ledger row; stdio interleaves calls, so each gets its own scope.
+                output = await runWithRequestStores(async () => {
+                    const text = await executeTool(toolName, toolArgs, ctx);
+                    await recordMcpTokens(toolName, text, ctx);
+                    return text;
+                });
+            }
+            catch (err) {
+                if (!(err instanceof RecallRequestError))
+                    throw err;
+                return invalidArgs(id, toolName, [err.message]);
             }
-            const output = await executeTool(toolName, toolArgs, ctx);
-            recordMcpTokens(toolName, output, ctx);
             return {
                 jsonrpc: '2.0',
                 id,

package/dist/mcp/session-state.d.ts

@@ -1,6 +1,4 @@
-import type { RingBuffer } from '../recall-history.js';
-export declare const sessionRecallHistoryMcp: Map<string, RingBuffer>;
-/** Test-only: reset the module-level recall-history Map. Call from beforeEach. */
+/** Test-only: reset the MCP recall rings. Call from beforeEach. */
 export declare function __resetSessionRecallHistoryMcp(): void;
 export declare const MAX_RECALL_CLIENTS = 4096;
 export declare const lastRecalledIds: Map<string, string[]>;

package/dist/mcp/session-state.js

@@ -1,10 +1,8 @@
 // Per-process state the MCP tools share across calls: recall rings, last recalled ids, auto-sleep runs.
-// Per-(tenant, session) recall-history rings for the MCP pipeline, kept apart from
-// the CLI/HTTP rings: each pipeline owns its rings, with no IPC between them.
-export const sessionRecallHistoryMcp = new Map();
-/** Test-only: reset the module-level recall-history Map. Call from beforeEach. */
+import { resetSessionRings } from '../api/recall-record.js';
+/** Test-only: reset the MCP recall rings. Call from beforeEach. */
 export function __resetSessionRecallHistoryMcp() {
-    sessionRecallHistoryMcp.clear();
+    resetSessionRings('mcp');
 }
 // ── Track last recalled IDs for outcome feedback ──
 //

package/dist/predictions/planning-fallacy.d.ts

@@ -1,3 +1,6 @@
+import { type AppendAuditOpts } from '../audit.js';
+import { type ForwardClaimMatch } from '../forward-claim-detector.js';
+import { type PredictionBaserate } from './store.js';
 /**
  * Surface delivered on `RecallResult.planningFallacyHint` when an
  * agent's recall query carries a forward-prediction phrase AND the closest
@@ -66,6 +69,49 @@ export interface ComputePlanningFallacyHintOpts {
      *  carry the right attribution instead of the 'cli' default. */
     actor?: string;
 }
+export interface ClassResolution {
+    classTag: string | null;
+    /** True when ≥2 classes tied at the best overlap score AND best ≥ 1.
+     *  Caller emits `recall_autodebias_hint_tiebreak` audit and returns
+     *  null hint (silent — prevents the "show wrong class half the time"
+     *  failure mode the alphabetical-tiebreak alternative would create). */
+    tiebreak: boolean;
+}
+/** The prediction class a forward claim resolves to, and that class's closed-prediction stats when one resolved. */
+export interface PlanningFallacyEvidence extends ClassResolution {
+    readonly baserate: PredictionBaserate | null;
+}
+/** The output a claim earns from its evidence, and the audit row that records the decision when there is one. */
+export interface PlanningFallacyDecision {
+    output: PlanningFallacyOutput;
+    audit?: AppendAuditOpts;
+}
+/**
+ * Resolve a query-token set to a unique best-matching class_tag for the
+ * tenant. Scores by lower-cased token overlap; requires best score ≥ 1
+ * AND strictly greater than the 2nd-best score.
+ *
+ * Indexed via idx_predictions_tenant_class (db.ts:1015) → O(log n) seek
+ * plus a small DISTINCT scan over the per-tenant class-tag set.
+ *
+ * Scope behaviour (deliberate): class_tag selection is TENANT-GLOBAL,
+ * NOT scope-filtered against
+ * the recall's opts.scope. The class_tag is an aggregator label across
+ * historical predictions in the class, not a per-memory scope-bound
+ * property. A no-scope recall CAN surface a class_tag from a privately-
+ * scoped prediction's class in PlanningFallacyHint.classTag — by design,
+ * because base-rate reasoning needs the full historical sample.
+ * Implications:
+ *   - The hint payload itself carries no memory content (only the aggregate
+ *     summary string + numeric stats), so memory bodies do not leak.
+ *   - The class_tag NAME is the side-channel. If sensitive labels are a
+ *     concern, callers should either use opaque class names (e.g. hashes
+ *     or numeric tokens) or set HIPPO_AUTODEBIAS=off.
+ *   - tests/api-recall-autodebias.test.ts locks this with an explicit
+ *     test asserting that scope-set predictions surface via no-scope
+ *     recalls (so future "fix" attempts that scope-filter trip CI).
+ */
+export declare function resolveClassFromTokens(hippoRoot: string, tenantId: string, queryTokens: readonly string[]): ClassResolution;
 /**
  * Planning-fallacy orchestrator.
  *
@@ -92,4 +138,10 @@ export interface ComputePlanningFallacyHintOpts {
  * Latency budget: well under 50ms; a miss pays only the regex.
  */
 export declare function computePlanningFallacyOutput(hippoRoot: string, tenantId: string, queryText: string, opts?: ComputePlanningFallacyHintOpts): PlanningFallacyOutput;
+/** The forward claim in a recall query; null when HIPPO_AUTODEBIAS=off, the query is empty or no claim matches. */
+export declare function detectPlanningClaim(queryText: string, opts?: ComputePlanningFallacyHintOpts): ForwardClaimMatch | null;
+/** Resolves a claim's tokens to one class and reads its baserate, writing no audit row. */
+export declare function planningFallacyEvidenceAt(hippoRoot: string, tenantId: string, classQueryTokens: readonly string[]): PlanningFallacyEvidence;
+/** The hint, the watching variant or nothing for a claim and its class evidence; reads and writes nothing itself. */
+export declare function decidePlanningFallacy(match: ForwardClaimMatch, evidence: PlanningFallacyEvidence, tenantId: string, actor: string): PlanningFallacyDecision;
 //# sourceMappingURL=planning-fallacy.d.ts.map