hippo-memory 1.64.1 → 1.66.0

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

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 ──
 //