hippo-memory 1.72.0 → 2.1.0

package/dist/mcp/protocol.js

@@ -7,8 +7,6 @@ import { errorFields, errorMessage, log } from '../util/log.js';
 import { currentRequestId } from '../util/request-scope.js';
 import { getGlobalRoot } from '../sharing/global-store.js';
 import { findHippoStoreDir } from '../core/project-identity.js';
-import { STORE_BUSY_MESSAGE } from '../store/port.js';
-import { isStoreBusy } from '../store/sqlite/busy.js';
 // ── Find hippo root ──
 /** Same bounded walk as the CLI (ends at home, so HIPPO_HOME wins over ~/.hippo); cwd/opts are the test seam. */
 export function findHippoRoot(cwd = process.cwd(), opts) {
@@ -19,14 +17,15 @@ export function findHippoRoot(cwd = process.cwd(), opts) {
     const global = getGlobalRoot();
     return fs.existsSync(global) ? global : null;
 }
-/** JSON-RPC reply for a request that threw: typed API errors keep their text; anything else is logged and answered generically. */
+/** JSON-RPC reply for a request that threw: typed API errors keep
+ * their text; anything else is logged and answered generically. */
 export function mcpErrorResponse(id, err, requestId = currentRequestId() ?? randomUUID(), call) {
     const where = call === undefined ? '' : ` (${call})`;
-    if (isStoreBusy(err)) {
+    const { status, message } = mapApiError(err);
+    if (status === 503) {
         log.warn(`mcp request${where} failed: ${errorMessage(err)}`, { requestId });
-        return { jsonrpc: '2.0', id, error: { code: -32603, message: STORE_BUSY_MESSAGE } };
+        return { jsonrpc: '2.0', id, error: { code: -32603, message } };
     }
-    const { status, message } = mapApiError(err);
     if (status !== 500) {
         log.info(`mcp request${where} failed: ${errorMessage(err)}`, { requestId, status });
         return { jsonrpc: '2.0', id, error: { code: -32603, message } };
@@ -38,12 +37,16 @@ export function mcpErrorResponse(id, err, requestId = currentRequestId() ?? rand
         error: { code: -32603, message: `${INTERNAL_ERROR_MESSAGE} (request id ${requestId})`, data: { requestId } },
     };
 }
-/** The api-layer actor for a tool call. Only stdio passes no context: it is the local operator, host admin. Any context runs as its own role, and an
- * untyped caller that sends none runs as a member, so a missing role fails closed. */
+/** The api-layer actor for a tool call. Only stdio passes no context: it is the local operator, host admin. Any context
+ * runs as its own role, and an untyped caller that sends none runs as a member, so a missing role fails closed. */
 export function mcpActor(ctx) {
     if (ctx === undefined)
         return { subject: 'mcp', role: 'admin', hostAdmin: true };
-    const actor = { subject: ctx.actor ?? 'mcp', role: ctx.role === 'admin' ? 'admin' : 'member', scopes: ctx.scopes };
+    const actor = {
+        subject: ctx.actor ?? 'mcp',
+        role: ctx.role === 'admin' ? 'admin' : 'member',
+        scopes: ctx.scopes,
+    };
     if (ctx.viaAuthResolver)
         actor.viaAuthResolver = true;
     if (ctx.hostAdmin)

package/dist/mcp/recall-tools.d.ts

@@ -1,6 +1,6 @@
 import { type ToolCall } from './protocol.js';
 export declare function runRecallTool(call: ToolCall): Promise<string>;
-export declare function runAssembleTool({ args, ctx, hippoRoot, tenantId }: ToolCall): Promise<string>;
-export declare function runDrillTool({ args, ctx, hippoRoot, tenantId }: ToolCall): Promise<string>;
-export declare function runContextTool({ args, ctx, hippoRoot, config, tenantId }: ToolCall): Promise<string>;
+export declare function runAssembleTool({ args, ctx, hippoRoot, tenantId, store }: ToolCall<'dagReads'>): Promise<string>;
+export declare function runDrillTool({ args, ctx, hippoRoot, tenantId, store }: ToolCall<'dagReads'>): Promise<string>;
+export declare function runContextTool({ args, ctx, hippoRoot, config, tenantId, store }: ToolCall<'contextReads'>): Promise<string>;
 //# sourceMappingURL=recall-tools.d.ts.map

package/dist/mcp/recall-tools.js

@@ -6,72 +6,58 @@ import { retrieve as apiRetrieve, drillDown as apiDrillDown, assemble as apiAsse
 import { autoDetectContext } from '../api/context-auto.js';
 import { resolveProjectIdentity } from '../core/project-identity.js';
 import { isSharedStore } from '../core/config.js';
-import { detectAnchoring, hashQueryText, biasHintEnabled, snapshotRing } from '../api/recall-history.js';
-import { detectAvailabilityBias } from '../api/availability.js';
+import { hashQueryText } from '../api/recall/finish.js';
+import { availabilityPool, cutoffClauses, detectRecallHints, shrinkToFit, suppressionSummary, tokenPurse, } from '../api/recall/render.js';
 import { estimateTokens } from '../util/token-text.js';
 import { assembleCost, assembleText, drillCost, drillText } from '../api/context-render.js';
 import { mcpActor, ownsServerCwd } 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 '../util/json.js';
-import { parseContextRequest, parseRecallRequest, toolParams } from '../api/recall-request.js';
-import { noteRecall, sessionRing, shownRecallRows } from '../api/recall-record.js';
+import { parseContextRequest, parseRecallRequest, toolParams } from '../api/recall/request.js';
+import { noteRecall, sessionRing, shownRecallRows } from '../api/recall/finish.js';
 // Candidate pool the MCP recall ranks before the token budget trims what is shown.
 const MCP_RECALL_LIMIT = 50;
-function detectBiasHints(list, pool, anchorRing, queryHash) {
-    const anchoring = anchorRing ? detectAnchoring(snapshotRing(anchorRing), queryHash, list[0]?.entry.id ?? null) : null;
-    const availability = biasHintEnabled('availability')
-        ? detectAvailabilityBias({
-            topK: list.map((r) => ({ id: r.entry.id, created: r.entry.created })),
-            pool: pool.map((e) => ({ id: e.id, created: e.created })),
-        })
-        : null;
-    return { anchoring, availability };
-}
 function biasHintSections(anchoring, availability) {
-    let text = anchoring ? `## Anchoring hint\n${anchoring.summary}\n[anchored_on: ${anchoring.memoryId}]\n\n---\n\n` : '';
+    let text = anchoring
+        ? `## Anchoring hint\n${anchoring.summary}\n[anchored_on: ${anchoring.memoryId}]\n\n---\n\n`
+        : '';
     if (availability)
         text += `## Availability bias\n${availability.summary}\n\n---\n\n`;
     return text;
 }
 function cutoffSection(s, shown) {
-    const cutoffClauses = [];
-    if (s.droppedByBudget > 0)
-        cutoffClauses.push(`${s.droppedByBudget} dropped to fit limit`);
-    if (s.droppedPreRank > 0)
-        cutoffClauses.push(`${s.droppedPreRank} filtered pre-rank`);
-    if (s.summarySubstitutionsAdded > 0)
-        cutoffClauses.push(`${s.summarySubstitutionsAdded} summary substitutions added`);
-    if (s.freshTailAdded > 0)
-        cutoffClauses.push(`${s.freshTailAdded} fresh-tail added`);
-    if (s.suppressedByInterference > 0)
-        cutoffClauses.push(`${s.suppressedByInterference} suppressed by interference`);
-    if (cutoffClauses.length === 0)
+    const clauses = cutoffClauses(s);
+    if (clauses.length === 0)
         return '';
-    return `## Cutoff\nShowing ${shown} of ${s.totalCandidates} candidates; ${cutoffClauses.join('; ')}.\n\n---\n\n`;
+    return `## Cutoff
+Showing ${shown} of ${s.totalCandidates} candidates; ${clauses.join('; ')}.
+
+---
+
+`;
 }
-function renderWithinBudget(ranked, limits, render) {
-    let results = fitBudget(ranked, Math.max(0, limits.room), 1, memoryCost);
-    let rendered = render(results);
-    // The hints, Cutoff block and heading vary with the list, so the lowest-ranked entry goes until the whole response fits.
-    while (results.length > 1 && estimateTokens(rendered.text) > limits.budget) {
-        results = results.slice(0, -1);
-        rendered = render(results);
-    }
-    return rendered;
+function suppressionCounts(i) {
+    return {
+        totalCandidates: i.poolSize + i.droppedByScope,
+        droppedPreRank: i.droppedByScope + i.cut.length - i.list.length, // the bucket CLI and API recall use for copies
+        droppedByBudget: Math.max(0, i.poolSize - i.cut.length), // an upper bound: rows that never matched count too
+        summarySubstitutionsAdded: i.tail.filter((r) => r.isSummary).length,
+        freshTailAdded: i.tail.filter((r) => r.isFreshTail && !r.isSummary).length,
+    };
+}
+function fitMcpRecall(ranked, limits, render) {
+    const fitted = fitBudget(ranked, Math.max(0, limits.room), 1, memoryCost);
+    return shrinkToFit(fitted.length, 1, limits.budget, (n) => render(fitted.slice(0, n)), (r) => r.text);
 }
 function recallPresenter(budget, options) {
     const { includeContinuity, anchorRing, queryHash, out, hintRows } = options;
     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);
-        const pays = (piece) => {
-            const tokens = estimateTokens(piece);
-            if (tokens > left)
-                return false;
-            left -= tokens;
-            return true;
-        };
+        // Sections are paid in print order, ahead of the memories and
+        // after the heading; one that does not fit is dropped whole.
+        const purse = tokenPurse(budget - memoriesReserve(budget));
+        const pays = (piece) => purse.pays(estimateTokens(piece));
+        const hintPool = availabilityPool(() => pool);
         const planPiece = planningSection(apiResult);
         const showPlan = planPiece !== '' && pays(planPiece);
         const tailRows = apiResult.results.filter((r) => r.isFreshTail || r.isSummary);
@@ -80,22 +66,18 @@ function recallPresenter(budget, options) {
         const showContinuity = continuityPiece !== '' && pays(continuityPiece);
         // The hints and Cutoff block describe the list MCP shows, not the window band in apiResult.
         const render = (cut) => {
-            const list = dropHeldCopies(cut, (r) => r.entry); // after every cut, so a merged row cut here never hides its sources
-            const { anchoring, availability } = detectBiasHints(list, pool, anchorRing, queryHash);
+            // After every cut, so a merged row cut here never hides its sources.
+            const list = dropHeldCopies(cut, (r) => r.entry);
+            const { anchoring, availability } = detectRecallHints({ list, pool: hintPool, anchorRing, queryHash });
             const shownIds = new Set(list.map((r) => r.entry.id));
             const shownKeys = storedTextKeys(list.map((r) => r.entry));
             const tail = showTail
                 ? dropHeldCopies(tailRows.filter((r) => !shownIds.has(r.id) && !shownKeys.has(duplicateKey(r.content))), (r) => r)
                 : [];
-            const s = {
-                totalCandidates: pool.length + droppedByScope,
-                droppedPreRank: droppedByScope + cut.length - list.length, // the bucket CLI and API recall put hidden copies in
-                droppedByBudget: Math.max(0, pool.length - cut.length), // an upper bound: rows that never matched count too
-                summarySubstitutionsAdded: tail.filter((r) => r.isSummary).length,
-                freshTailAdded: tail.filter((r) => r.isFreshTail && !r.isSummary).length,
-                suppressedByInterference: anchoring?.reason === 'memory_dominance' ? 1 : 0,
-            };
-            // Anchoring is the stronger pull, so it prints first; the Cutoff block sits above the list, where the agent reads it.
+            const counts = suppressionCounts({ poolSize: pool.length, droppedByScope, cut, list, tail });
+            const s = suppressionSummary(counts, anchoring);
+            // Anchoring is the stronger pull, so it prints first; the
+            // Cutoff block sits above the list, where the agent reads it.
             let text = biasHintSections(anchoring, availability);
             if (showPlan)
                 text += planPiece;
@@ -104,13 +86,13 @@ function recallPresenter(budget, options) {
             text += formatMemories(list) + tailSection(tail) + (showContinuity ? continuityPiece : '');
             return { anchoring, availability, text, list };
         };
-        const rendered = renderWithinBudget(ranked, { room: left, budget }, render);
+        const rendered = fitMcpRecall(ranked, { room: purse.left(), budget }, render);
         out.rendered = rendered;
         return { ids: rendered.list.map((r) => r.entry.id), audit: hintRows(rendered) };
     };
 }
 export async function runRecallTool(call) {
-    const { ctx, hippoRoot, config, tenantId, args } = call;
+    const { ctx, hippoRoot, config, tenantId, args, store } = 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;
@@ -119,7 +101,8 @@ export async function runRecallTool(call) {
         hippoRoot,
         tenantId,
         actor: mcpActor(ctx),
-        store: ctx?.store,
+        store,
+        reach: ctx?.reach,
     };
     const anchorRing = sessionRing('mcp', tenantId, sessionId);
     const who = { tenantId, actor: ctx?.actor ?? 'mcp' };
@@ -135,22 +118,24 @@ export async function runRecallTool(call) {
         keepHeldCopies: true,
         project: ctx?.project,
         showRanked: recallPresenter(budget, {
-            includeContinuity, anchorRing, queryHash, out,
-            hintRows: ({ list, anchoring, availability }) => shownRecallRows(who, {
-                query, ring: anchorRing, topId: list[0]?.entry.id ?? null, anchoring, availability,
-            }),
+            includeContinuity,
+            anchorRing,
+            queryHash,
+            out,
+            hintRows: ({ list, anchoring, availability }) => shownRecallRows(who, { query, ring: anchorRing, topId: list[0]?.entry.id ?? null, anchoring, availability }),
         }),
     });
     const { rendered } = out;
     if (!rendered)
         throw new Error('hippo_recall: api.retrieve returned without calling showRanked');
     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.
+    // 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 async function runAssembleTool({ args, ctx, hippoRoot, tenantId }) {
+export async function runAssembleTool({ args, ctx, hippoRoot, tenantId, store }) {
     const sessionId = String(args.session_id || '');
     if (!sessionId)
         return 'No session_id provided.';
@@ -161,7 +146,7 @@ export async function runAssembleTool({ args, ctx, hippoRoot, tenantId }) {
         hippoRoot,
         tenantId,
         actor: mcpActor(ctx),
-        store: ctx?.store,
+        store,
     };
     const explicitScope = isJsonString(args.scope) && args.scope.length > 0
         ? args.scope
@@ -181,7 +166,7 @@ export async function runAssembleTool({ args, ctx, hippoRoot, tenantId }) {
     });
     return assembleText(r);
 }
-export async function runDrillTool({ args, ctx, hippoRoot, tenantId }) {
+export async function runDrillTool({ args, ctx, hippoRoot, tenantId, store }) {
     const summaryId = String(args.summary_id || '');
     if (!summaryId)
         return 'No summary_id provided.';
@@ -193,7 +178,7 @@ export async function runDrillTool({ args, ctx, hippoRoot, tenantId }) {
         hippoRoot,
         tenantId,
         actor: mcpActor(ctx),
-        store: ctx?.store,
+        store,
     };
     const drillExtra = {};
     if (Number.isFinite(limit) && limit > 0)
@@ -213,15 +198,17 @@ export async function runDrillTool({ args, ctx, hippoRoot, tenantId }) {
     }
     return drillText(r);
 }
-// The served store names the project (an HTTP daemon runs from anywhere); the global root names none, so only an owner of the server cwd falls back to it.
+// The served store names the project (an HTTP daemon runs from anywhere); the global root names none, so only an owner
+// of the server cwd falls back to it.
 function localProject(hippoRoot, ownsCwd) {
     const storeProject = resolveProjectIdentity(path.dirname(path.resolve(hippoRoot)));
     return storeProject.name !== '' || !ownsCwd ? storeProject : resolveProjectIdentity(process.cwd());
 }
-export async function runContextTool({ args, ctx, hippoRoot, config, tenantId }) {
+export async function runContextTool({ args, ctx, hippoRoot, config, tenantId, store }) {
     // 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)
+    if ((ctx?.reach ? ctx.reach.shared : isSharedStore(hippoRoot)) && ctx?.project === undefined) {
         return 'hippo_context needs a project on a shared store; use hippo_recall';
+    }
     const { budget: budgetArg, scope: exactScope } = parseContextRequest(toolParams(args));
     const budget = budgetArg ?? config.defaultContextBudget;
     if (budget === 0)
@@ -229,8 +216,9 @@ export async function runContextTool({ args, ctx, hippoRoot, config, tenantId })
     if (budget < memoriesReserve(budget))
         return ''; // not even the heading fits, so nothing prints, as at budget 0
     const ownsCwd = ownsServerCwd(ctx);
-    const result = await apiGetContext({ hippoRoot, tenantId, actor: mcpActor(ctx), store: ctx?.store }, {
-        // The server's git state is no remote caller's, so a project or remote caller gets rows by strength without a query.
+    const result = await apiGetContext({ hippoRoot, tenantId, actor: mcpActor(ctx), store, reach: ctx?.reach }, {
+        // The server's git state is no remote caller's, so a project
+        // or remote caller gets rows by strength without a query.
         q: ctx?.project || !ownsCwd ? undefined : autoDetectContext(),
         budget,
         exactScope,

package/dist/mcp/request.d.ts

@@ -1,7 +1,9 @@
 import { type McpContext, type McpRequest, type McpResponse } from './protocol.js';
-/** Records the memory text a recall or context tool returned; best-effort (a ledger failure never fails the call), other tools are not recorded. */
-export declare function recordMcpTokens(toolName: string, output: string, ctx?: McpContext): Promise<void>;
-/** Transport-agnostic MCP dispatcher: the stdio loop and the HTTP/SSE transport route every JSON-RPC message through it. Returns null for notifications.
- * Errors thrown by `executeTool` are the caller's problem: wrap with try/catch on the transport side. */
-export declare function handleMcpRequest(req: McpRequest, ctx?: McpContext): Promise<McpResponse | null>;
+/** Records the memory text a recall or context tool returned; best-effort (a ledger failure never fails the call),
+ * other tools are not recorded. */
+export declare function recordMcpTokens(toolName: string, output: string, ctx: McpContext): Promise<void>;
+/** Transport-agnostic MCP dispatcher: the stdio loop and the HTTP/SSE transport route every JSON-RPC message through
+ * it. Returns null for notifications. `executeTool` errors are the caller's problem: wrap with try/catch in the
+ * transport. Only `tools/call` needs the context, so stdio builds one for that method alone. */
+export declare function handleMcpRequest(req: McpRequest, ctx: McpContext | undefined): Promise<McpResponse | null>;
 //# sourceMappingURL=request.d.ts.map

package/dist/mcp/request.js

@@ -1,95 +1,70 @@
 // Transport-agnostic request handling: tool dispatch table, tool execution and the JSON-RPC method switch.
-import { errorMessage, log } from '../util/log.js';
+import { currentSignal } from '../util/request-scope.js';
 import { STORE_NOT_PORTED_MESSAGE } from '../util/http-util.js';
-import { getGlobalRoot, initGlobal } from '../sharing/global-store.js';
 import { loadConfig } from '../core/config.js';
-import { resolveTenantId } from '../store/tenant.js';
-import { runWithRequestStores } from '../db/index.js';
-import { rethrowIfSqliteBlocked } from '../util/sqlite-blocked.js';
-import { hasGroup, storeFor } from '../store/index.js';
+import { hasGroup, narrowStore } from '../store/index.js';
 import { estimateTokens } from '../util/token-text.js';
 import { PACKAGE_VERSION } from '../util/version.js';
 import { validateToolArgs } from './tool-args.js';
-import { RecallRequestError } from '../api/recall-request.js';
-import { findHippoRoot } from './protocol.js';
+import { RecallRequestError } from '../api/recall/request.js';
+import { recordTokens } from '../api/tokens.js';
+import { mcpActor, } from './protocol.js';
 import { TOOLS, TOOLS_BY_NAME, ARGS_CHECKED_BY_API } from './tools.js';
 import { runRecallTool, runAssembleTool, runDrillTool, runContextTool } from './recall-tools.js';
 import { runRememberTool, runOutcomeTool, runLearnTool } from './memory-tools.js';
-import { runPredictBaserateTool, runStatusTool, runConflictsTool, runResolveTool, runShareTool, runPeersTool } from './admin-tools.js';
+import { runPredictBaserateTool, runStatusTool, runConflictsTool, runResolveTool, runShareTool, runPeersTool, } from './admin-tools.js';
 import { sharedStoreRefusal } from './shared-gate.js';
 import { isJsonString, isJsonObject } from '../util/json.js';
-/** Zero-install first run (`npx -y hippo-memory mcp`, no store anywhere): create the global store instead of failing every tool call, and say so on stderr
- * (stdout carries the protocol). A later `hippo init` project store takes precedence. */
-function createGlobalStoreOnFirstRun() {
-    initGlobal();
-    const root = getGlobalRoot();
-    log.warn(`no memory store found; created the global store at ${root}. Run \`hippo init\` in a project for a project store.`);
-    return root;
-}
 // ── Token ledger ──
 const MCP_TOKEN_SURFACES = new Map([
     ['hippo_recall', 'mcp_recall'],
     ['hippo_context', 'mcp_context'],
 ]);
-/** Records the memory text a recall or context tool returned; best-effort (a ledger failure never fails the call), other tools are not recorded. */
+/** Records the memory text a recall or context tool returned; best-effort (a ledger failure never fails the call),
+ * other tools are not recorded. */
 export async function recordMcpTokens(toolName, output, ctx) {
     const surface = MCP_TOKEN_SURFACES.get(toolName);
     if (!surface || !output)
         return;
-    try {
-        const hippoRoot = ctx?.hippoRoot ?? findHippoRoot();
-        if (!hippoRoot)
-            return;
-        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: ${errorMessage(err)}`);
-    }
+    const apiCtx = { hippoRoot: ctx.hippoRoot, tenantId: ctx.tenantId, actor: mcpActor(ctx), store: ctx.store };
+    await recordTokens(apiCtx, surface, { items: 0, tokens: estimateTokens(output) });
+}
+/** A tool that reaches its store through `group`: the call it gets carries the store narrowed to it. */
+function toolOn(group, handler) {
+    return {
+        storeReady: group,
+        run: (call) => handler({ ...call, store: narrowStore(call.store, group) }),
+    };
 }
 const TOOL_HANDLERS = new Map([
-    ['hippo_recall', { handler: runRecallTool, storeReady: 'base' }],
-    ['hippo_assemble', { handler: runAssembleTool, storeReady: 'dagReads' }],
-    ['hippo_drill', { handler: runDrillTool, storeReady: 'dagReads' }],
-    ['hippo_predict_baserate', { handler: runPredictBaserateTool, storeReady: 'predictions' }],
-    ['hippo_remember', { handler: runRememberTool, storeReady: 'entryWrites' }],
-    ['hippo_outcome', { handler: runOutcomeTool, storeReady: 'entryWrites' }],
-    ['hippo_context', { handler: runContextTool, storeReady: 'contextReads' }],
-    ['hippo_status', { handler: runStatusTool }],
-    ['hippo_learn', { handler: runLearnTool }],
-    ['hippo_conflicts', { handler: runConflictsTool }],
-    ['hippo_resolve', { handler: runResolveTool }],
-    ['hippo_share', { handler: runShareTool }],
-    ['hippo_peers', { handler: runPeersTool }],
+    ['hippo_recall', toolOn('base', runRecallTool)],
+    ['hippo_assemble', toolOn('dagReads', runAssembleTool)],
+    ['hippo_drill', toolOn('dagReads', runDrillTool)],
+    ['hippo_predict_baserate', toolOn('predictions', runPredictBaserateTool)],
+    ['hippo_remember', toolOn('entryWrites', runRememberTool)],
+    ['hippo_outcome', toolOn('entryWrites', runOutcomeTool)],
+    ['hippo_context', toolOn('contextReads', runContextTool)],
+    ['hippo_status', toolOn('reports', runStatusTool)],
+    ['hippo_learn', toolOn('lessonWrites', runLearnTool)],
+    ['hippo_conflicts', toolOn('conflicts', runConflictsTool)],
+    ['hippo_resolve', toolOn('conflicts', runResolveTool)],
+    ['hippo_share', { run: runShareTool }],
+    ['hippo_peers', { run: runPeersTool }],
 ]);
-/** The served store when it is not hippo.db, else null. */
-function otherStore(ctx) {
-    const store = ctx?.store;
-    return store !== undefined && store.kind !== 'sqlite' ? store : null;
-}
+/** A call with no context yet (tools/list on stdio) lists every tool. */
 function runsOn(store, toolName) {
-    const group = TOOL_HANDLERS.get(toolName)?.storeReady;
-    return group !== undefined && hasGroup(store, group);
+    return store === undefined || hasGroup(store, TOOL_HANDLERS.get(toolName)?.storeReady ?? 'localFiles');
 }
 async function executeTool(name, args, ctx) {
-    // With a transport context (HTTP), trust it: hippoRoot comes from the server's bound opts and tenantId from the Bearer (or loopback fallback).
-    // Stdio walks from cwd / the global root and resolves tenant from HIPPO_TENANT.
-    const hippoRoot = ctx?.hippoRoot ?? findHippoRoot() ?? createGlobalStoreOnFirstRun();
+    // The transport's context is trusted: its hippoRoot, store and tenantId were bound by the host (the HTTP server's
+    // Bearer, or the stdio host's folder walk and HIPPO_TENANT).
+    const { hippoRoot, tenantId } = ctx;
     const config = loadConfig(hippoRoot);
-    // Every store read here is tenant-isolated, resolved once per tool call; prefer the transport's ctx.tenantId so an HTTP Bearer for tenant B
-    // does not drop to HIPPO_TENANT.
-    const tenantId = ctx?.tenantId ?? resolveTenantId({});
-    const handler = TOOL_HANDLERS.get(name)?.handler;
+    const run = TOOL_HANDLERS.get(name)?.run;
     // handleMcpRequest rejects names missing from TOOLS, so reaching here means TOOLS and this table drifted apart.
-    if (!handler)
+    if (!run)
         throw new Error(`hippo-mcp: tool ${name} is declared but has no handler`);
-    return handler({ args, ctx, hippoRoot, config, tenantId });
+    return run({ args, ctx, hippoRoot, store: ctx.store, config, tenantId });
 }
 // ── Request handling ──
 // The MCP spec reports input validation as a tool result with isError, so the model can read it and retry.
@@ -97,9 +72,21 @@ function invalidArgs(id, toolName, problems) {
     return {
         jsonrpc: '2.0',
         id,
-        result: { content: [{ type: 'text', text: `Invalid arguments for ${toolName}: ${problems.join('; ')}` }], isError: true },
+        result: {
+            content: [{ type: 'text', text: `Invalid arguments for ${toolName}: ${problems.join('; ')}` }],
+            isError: true,
+        },
     };
 }
+/** The tool and its ledger row run in the caller's request scope, which the host (server or stdio) opens.
+ * SHORTCUT: the deadline stops a call only between these steps, not a running store read or fetch; thread the signal */
+async function runTool(toolName, args, ctx) {
+    currentSignal()?.throwIfAborted();
+    const text = await executeTool(toolName, args, ctx);
+    currentSignal()?.throwIfAborted();
+    await recordMcpTokens(toolName, text, ctx);
+    return text;
+}
 async function callTool(id, params, ctx) {
     const nameValue = params?.name;
     const toolName = isJsonString(nameValue) ? nameValue : '';
@@ -108,13 +95,13 @@ async function callTool(id, params, ctx) {
         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.
-    const other = otherStore(ctx);
-    if (other && !runsOn(other, toolName)) {
+    if (!runsOn(ctx.store, toolName)) {
         return { jsonrpc: '2.0', id, error: { code: -32603, message: STORE_NOT_PORTED_MESSAGE } };
     }
     const refusal = sharedStoreRefusal(toolName, ctx);
-    if (refusal !== undefined)
+    if (refusal !== undefined) {
         return { jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: refusal }], isError: true } };
+    }
     const argumentsValue = params?.arguments;
     if (argumentsValue !== undefined && argumentsValue !== null && !isJsonObject(argumentsValue)) {
         return { jsonrpc: '2.0', id, error: { code: -32602, message: `${toolName}: arguments must be an object` } };
@@ -125,12 +112,7 @@ async function callTool(id, params, ctx) {
         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;
-        });
+        output = await runTool(toolName, toolArgs, ctx);
     }
     catch (err) {
         if (!(err instanceof RecallRequestError))
@@ -145,8 +127,9 @@ async function callTool(id, params, ctx) {
         },
     };
 }
-/** Transport-agnostic MCP dispatcher: the stdio loop and the HTTP/SSE transport route every JSON-RPC message through it. Returns null for notifications.
- * Errors thrown by `executeTool` are the caller's problem: wrap with try/catch on the transport side. */
+/** Transport-agnostic MCP dispatcher: the stdio loop and the HTTP/SSE transport route every JSON-RPC message through
+ * it. Returns null for notifications. `executeTool` errors are the caller's problem: wrap with try/catch in the
+ * transport. Only `tools/call` needs the context, so stdio builds one for that method alone. */
 export async function handleMcpRequest(req, ctx) {
     const { id, method, params } = req;
     switch (method) {
@@ -163,10 +146,11 @@ export async function handleMcpRequest(req, ctx) {
         case 'notifications/initialized':
             return null;
         case 'tools/list': {
-            const other = otherStore(ctx);
-            return { jsonrpc: '2.0', id, result: { tools: other ? TOOLS.filter((t) => runsOn(other, t.name)) : TOOLS } };
+            return { jsonrpc: '2.0', id, result: { tools: TOOLS.filter((t) => runsOn(ctx?.store, t.name)) } };
         }
         case 'tools/call':
+            if (ctx === undefined)
+                throw new Error('hippo-mcp: tools/call needs a context');
             return callTool(id, params, ctx);
         default:
             // Notifications (no id) must not receive a response

package/dist/mcp/server.d.ts

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
-/** Hippo Memory MCP server: exposes hippo memory as MCP tools over stdio via the programmatic API (no child process). Usage: hippo mcp (or npx hippo-memory
+/**
+ * Hippo Memory MCP server: exposes hippo memory as MCP tools over stdio via the programmatic API (no child process).
+ * Usage: hippo mcp (or npx hippo-memory
  * mcp). */
 export { _resetSessionRecallHistoryMcpForTests } from './session-state.js';
 export { findHippoRoot, mcpErrorResponse, type McpRequest, type McpResponse, type McpContext } from './protocol.js';

package/dist/mcp/server.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
-/** Hippo Memory MCP server: exposes hippo memory as MCP tools over stdio via the programmatic API (no child process). Usage: hippo mcp (or npx hippo-memory
+/**
+ * Hippo Memory MCP server: exposes hippo memory as MCP tools over stdio via the programmatic API (no child process).
+ * Usage: hippo mcp (or npx hippo-memory
  * mcp). */
 export { _resetSessionRecallHistoryMcpForTests } from './session-state.js';
 export { findHippoRoot, mcpErrorResponse } from './protocol.js';
@@ -7,7 +9,8 @@ export { handleMcpRequest } from './request.js';
 export { startStdioLoop } from './stdio.js';
 import { envMcpStdio } from '../util/env.js';
 import { startStdioLoop } from './stdio.js';
-// Auto-start only as the main module (node dist/mcp/server.js or the cli's import('./mcp/server.js')); importing it elsewhere (the HTTP/SSE wiring) must not
+// Auto-start only as the main module (node dist/mcp/server.js or the cli's import('./mcp/server.js')); importing it
+// elsewhere (the HTTP/SSE wiring) must not
 // start stdio. Fallback: HIPPO_MCP_STDIO=1 or argv1 ending in /mcp/server.js also starts it.
 const isMainModule = (() => {
     try {
@@ -25,6 +28,8 @@ const isMainModule = (() => {
     }
 })();
 if (isMainModule) {
-    startStdioLoop();
+    // The CLI owns the store build, so running this file directly opens the same store `hippo mcp` does.
+    const { cliStdioHost } = await import('../cli/api-context.js');
+    startStdioLoop(cliStdioHost);
 }
 //# sourceMappingURL=server.js.map

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

@@ -1,7 +1,7 @@
 /** Test-only: reset the MCP recall rings. Call from beforeEach. */
 export declare function _resetSessionRecallHistoryMcpForTests(): void;
 export declare const lastRecalledIds: Map<string, string[]>;
-export { autoSleepInFlight } from '../api/auto-sleep.js';
+export { autoSleepInFlight } from '../api/sleep/auto-sleep.js';
 export declare function resolveClientKey(ctx: {
     clientKey?: string;
     tenantId: string;

package/dist/mcp/session-state.js

@@ -1,11 +1,12 @@
 // Per-process state the MCP tools share across calls: recall rings, last recalled ids, auto-sleep runs.
 import { DEFAULT_TENANT_ID } from '../util/env.js';
-import { resetSessionRings } from '../api/recall-record.js';
+import { resetSessionRings } from '../api/recall/finish.js';
 /** Test-only: reset the MCP recall rings. Call from beforeEach. */
 export function _resetSessionRecallHistoryMcpForTests() {
     resetSessionRings('mcp');
 }
-// Last recalled IDs per client for outcome feedback, so two HTTP-MCP clients on one tenant cannot poison each other: key is `ctx.clientKey` (hash of
+// Last recalled IDs per client for outcome feedback, so two HTTP-MCP clients on one tenant cannot poison each other:
+// key is `ctx.clientKey` (hash of
 // bearer+remoteAddr over HTTP), else 'stdio-${pid}', else `${tenantId}:default` for a McpContext built in tests.
 const MAX_RECALL_CLIENTS = 4096;
 // The caller names the project half of each key, so a set past the cap drops the client that recalled longest ago.
@@ -20,7 +21,7 @@ class RecentRecalls extends Map {
     }
 }
 export const lastRecalledIds = new RecentRecalls();
-export { autoSleepInFlight } from '../api/auto-sleep.js';
+export { autoSleepInFlight } from '../api/sleep/auto-sleep.js';
 export function resolveClientKey(ctx) {
     const base = ctx?.clientKey ? ctx.clientKey : `stdio-${process.pid}:${ctx?.tenantId || DEFAULT_TENANT_ID}`;
     return ctx?.project ? `${base}:${ctx.project.name}` : base;

package/dist/mcp/shared-gate.d.ts

@@ -1,4 +1,5 @@
 import type { McpContext } from './protocol.js';
-/** The refusal text for this call, or undefined when it may run; stdio passes no context and is never gated. */
-export declare function sharedStoreRefusal(name: string, ctx: McpContext | undefined): string | undefined;
+/** The refusal text for this call, or undefined when it may run; the stdio host is the operator's own process and is
+ * never gated. */
+export declare function sharedStoreRefusal(name: string, ctx: McpContext): string | undefined;
 //# sourceMappingURL=shared-gate.d.ts.map