hippo-memory 1.60.0 → 1.61.0

package/dist/mcp/server.js

@@ -7,1195 +7,12 @@
  *
  * Usage: hippo mcp (or npx hippo-memory mcp)
  */
-import * as fs from 'fs';
-import * as path from 'path';
-import { randomUUID } from 'node:crypto';
-import { INTERNAL_ERROR_MESSAGE, mapApiError } from '../http-util.js';
-import { log } from '../log.js';
-import { createMemory, Layer, calculateStrength, } from '../memory.js';
-import { fitBudget, estimateTokens } from '../search.js';
-import { evalNow } from '../ablation.js';
-import { loadStrengthRows, loadTextsHoldingWords, writeEntry, readEntry, listMemoryConflicts, resolveConflict, countCreatedSinceLastSleep } from '../store.js';
-import { shareMemory, listPeers, getGlobalRoot, initGlobal } from '../shared.js';
-import { consolidate } from '../consolidate.js';
-import { fetchGitLog, extractLessons, partitionLessons, isGitRepo } from '../autolearn.js';
-import { dropHeldCopies, duplicateKey, longestWord, storedTextKeys } from '../same-text.js';
-import { loadConfig } from '../config.js';
-import { confidenceLabel } from '../memory.js';
-import { resolveTenantId } from '../tenant.js';
-import { retrieve as apiRetrieve, remember as apiRemember, outcome as apiOutcome, drillDown as apiDrillDown, assemble as apiAssemble, getContext as apiGetContext, buildSuppressionSummary } from '../api.js';
-import { autoDetectContext } from '../context-auto.js';
-import { resolveProjectIdentity, findHippoStoreDir } from '../project-identity.js';
-import { computePredictionBaserate } from '../predictions.js';
-import { appendAuditEvent, auditQueryFields } from '../audit.js';
-import { RejectedValueError } from '../rejection.js';
-import { detectAnchoring, hashQueryText, biasHintEnabled, buildSessionKey, getOrCreateRing, appendRecall, snapshotRing, } from '../recall-history.js';
-import { detectAvailabilityBias } from '../availability.js';
-// v0.33 / J1 — Module-level per-(tenant, session) recall-history ring map
-// for the MCP pipeline. Separate from CLI/HTTP rings per plan v3
-// architecture (per-pipeline rings; no IPC).
-const sessionRecallHistoryMcp = new Map();
-/** Test-only: reset the module-level recall-history Map. Call from beforeEach. */
-export function __resetSessionRecallHistoryMcp() {
-    sessionRecallHistoryMcp.clear();
-}
-import { openHippoDb, closeHippoDb } from '../db.js';
-import { recordTokenUse } from '../token-ledger.js';
-import { PACKAGE_VERSION } from '../version.js';
-import { validateToolArgs } from './tool-args.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) {
-    const local = findHippoStoreDir(cwd, opts);
-    if (local !== null)
-        return local;
-    // Global fallback (respects $HIPPO_HOME / $XDG_DATA_HOME)
-    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. */
-export function mcpErrorResponse(id, err, requestId = randomUUID()) {
-    const { status, message } = mapApiError(err);
-    if (status !== 500)
-        return { jsonrpc: '2.0', id, error: { code: -32603, message } };
-    log.error(`mcp request failed: ${err instanceof Error ? err.message : String(err)}`, { requestId });
-    return {
-        jsonrpc: '2.0',
-        id,
-        error: { code: -32603, message: `${INTERNAL_ERROR_MESSAGE} (request id ${requestId})`, data: { requestId } },
-    };
-}
-/**
- * The api-layer actor for a tool call. Stdio (no ctx) is the local operator
- * and runs as admin; over HTTP the transport's authenticated role is used, so
- * a member key never acts as admin through MCP.
- */
-function mcpActor(ctx) {
-    const actor = { subject: ctx?.actor ?? 'mcp', role: ctx?.role ?? 'admin', scopes: ctx?.scopes };
-    if (ctx?.viaAuthResolver)
-        actor.viaAuthResolver = true;
-    return actor;
-}
-// MCP stdio transport spec: messages are newline-delimited JSON-RPC, no embedded newlines.
-// https://modelcontextprotocol.io/specification/.../basic/transports#stdio
-function send(msg) {
-    process.stdout.write(JSON.stringify(msg) + '\n');
-}
-function isJsonString(v) {
-    return typeof v === 'string';
-}
-function isJsonBoolean(v) {
-    return typeof v === 'boolean';
-}
-function isJsonObjectRecord(v) {
-    return v !== undefined && v !== null && typeof v === 'object' && !Array.isArray(v);
-}
-import { formatHandoffEvidenceLine } from '../handoff.js';
-import { assembleCost, assembleText, drillCost, drillText, printedTokens } from '../context-render.js';
-function handoffLines(h) {
-    const lines = [`- Summary: ${h.summary}`];
-    if (h.nextAction)
-        lines.push(`- Next action: ${h.nextAction}`);
-    if ((h.artifacts ?? []).length > 0)
-        lines.push(`- Artifacts: ${(h.artifacts ?? []).join(', ')}`);
-    if (h.outcome)
-        lines.push(`- Outcome: ${h.outcome}`);
-    if (h.targetRuntime)
-        lines.push(`- Target runtime: ${h.targetRuntime}`);
-    if (h.cardId)
-        lines.push(`- Card: ${h.cardId}`);
-    if ((h.constraints ?? []).length > 0)
-        lines.push(`- Constraints: ${(h.constraints ?? []).join(', ')}`);
-    if (h.evidence)
-        lines.push(`- Evidence: ${formatHandoffEvidenceLine(h.evidence)}`);
-    return lines;
-}
-function trailLines(events) {
-    return events.map((e) => {
-        const preview = e.content.length > 200 ? e.content.slice(0, 200) + '…' : e.content;
-        return `- [${e.event_type}] ${preview}`;
-    });
-}
-function formatContinuityBlock(block) {
-    const lines = ['## Continuity'];
-    if (block.activeSnapshot) {
-        lines.push('');
-        lines.push('### Active Task Snapshot');
-        lines.push(`- Task: ${block.activeSnapshot.task}`);
-        lines.push(`- Summary: ${block.activeSnapshot.summary}`);
-        lines.push(`- Next: ${block.activeSnapshot.next_step}`);
-    }
-    if (block.sessionHandoff) {
-        lines.push('');
-        lines.push('### Session Handoff');
-        lines.push(...handoffLines(block.sessionHandoff));
-    }
-    if (block.recentSessionEvents.length > 0) {
-        lines.push('');
-        lines.push('### Recent Session Trail');
-        lines.push(...trailLines(block.recentSessionEvents));
-    }
-    if (lines.length === 1) {
-        lines.push('');
-        lines.push('(no active task snapshot, handoff, or recent events for this tenant)');
-    }
-    return lines.join('\n');
-}
-const NO_MEMORIES = 'No relevant memories found.';
-function memoriesHeading(count) {
-    return `Found ${count} memories:\n`;
-}
-function formatMemory(r) {
-    const conf = confidenceLabel(r.entry).text;
-    const tags = r.entry.tags.length > 0 ? ` tags: ${r.entry.tags.join(', ')}` : '';
-    return `[${conf}]${tags} (strength=${r.entry.strength.toFixed(2)})\n${r.entry.content}\n`;
-}
-function formatMemories(results) {
-    if (results.length === 0)
-        return NO_MEMORIES;
-    return [memoriesHeading(results.length), ...results.map(formatMemory)].join('\n');
-}
-/** What a memory costs the budget: the text formatMemories prints for it. */
-const memoryCost = (r) => printedTokens(formatMemory(r));
-// The widest heading or the empty-list line, whichever costs more, so either prints inside the budget.
-function memoriesReserve(budget) {
-    return Math.max(printedTokens(memoriesHeading(budget)), estimateTokens(NO_MEMORIES));
-}
-function snapshotPiece(s) {
-    return [
-        '## Active Task Snapshot',
-        `- Task: ${s.task}`,
-        `- Status: ${s.status}`,
-        `- Updated: ${s.updated_at}`,
-        '',
-        '### Summary',
-        s.summary,
-        '',
-        '### Next step',
-        s.next_step,
-        '',
-        '',
-    ].join('\n');
-}
-function handoffPiece(h) {
-    return ['## Session Handoff', ...handoffLines(h), '', ''].join('\n');
-}
-function trailPiece(events) {
-    return ['## Recent Session Trail', ...trailLines(events), '', ''].join('\n');
-}
-// Sections print ahead of the memories in hippo_context, so getContext pays for each as printed before any memory.
-const contextCost = {
-    entry: memoryCost,
-    fixed: (budget) => memoriesReserve(budget),
-    snapshot: (s) => estimateTokens(snapshotPiece(s)),
-    handoff: (h) => estimateTokens(handoffPiece(h)),
-    trail: (events) => estimateTokens(trailPiece(events)),
-};
-// Rows the ranked list already shows drop out of this section, so pricing every row bounds what it prints.
-function tailSection(rows) {
-    if (rows.length === 0)
-        return '';
-    const lines = ['', '## Fresh tail / substituted summaries'];
-    for (const r of rows) {
-        const tag = r.isSummary ? '[summary]' : '[tail]';
-        const head = r.content.length > 200 ? r.content.slice(0, 200) + '…' : r.content;
-        if (r.isSummary && r.substitutedFor && r.substitutedFor.length > 0) {
-            lines.push(`- ${tag} ${r.id} (covers ${r.substitutedFor.length} rows): ${head}`);
-        }
-        else {
-            lines.push(`- ${tag} ${r.id}: ${head}`);
-        }
-    }
-    return '\n' + lines.join('\n');
-}
-// J3.2: the hint depends on the query alone, so api.retrieve's copy is the one shown; JSON.stringify fences the phrase.
-function planningSection(r) {
-    if (r.planningFallacyHint) {
-        const h = r.planningFallacyHint;
-        return `## Planning fallacy hint\nClass: ${h.classTag}\n${h.baserateSummary}\n(detected: ${JSON.stringify(h.detectedPhrase)})\n\n---\n\n`;
-    }
-    if (r.planningFallacyWatching) {
-        const w = r.planningFallacyWatching;
-        return `## Planning fallacy watch\nReason: ${w.reason}\n${w.suggestion}\n(detected: ${JSON.stringify(w.detectedPhrase)})\n\n---\n\n`;
-    }
-    return '';
-}
-// ── Tool definitions ──
-// HTTP sets no budget cap; 25x the 4000 recall default leaves room for large-context clients while bounding one call's work.
-const MAX_BUDGET_TOKENS = 100_000;
-// Same ceiling as the HTTP list routes' parseListLimit.
-const MAX_LIST_LIMIT = 1000;
-const TOOLS = [
-    {
-        name: 'hippo_recall',
-        description: 'Retrieve relevant memories from the project memory store. Returns memories ranked by relevance, strength, and recency within the token budget. Use at session start or when you need context about a topic. Pass include_continuity=true to also surface the active task snapshot, latest matching session handoff, and recent session events as a "## Continuity" appendix.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                query: { type: 'string', description: 'What to search for in memory (natural language)' },
-                budget: {
-                    type: 'number',
-                    minimum: 0,
-                    maximum: MAX_BUDGET_TOKENS,
-                    description: `Max tokens to return (default: config.defaultBudget, 4000; max ${MAX_BUDGET_TOKENS})`,
-                },
-                include_continuity: {
-                    type: 'boolean',
-                    description: 'Append continuity context (active snapshot + handoff + last 5 session events) below the memory results. Useful at session boot.',
-                },
-                scope: {
-                    type: 'string',
-                    description: 'Restrict results and continuity to memories/rows matching this scope exactly. When omitted, default-deny applies to ANY <source>:private:* (slack, github, ...) and unknown-legacy rows.',
-                },
-                fresh_tail_count: {
-                    type: 'number',
-                    description: 'When > 0, surface the last N kind=raw rows tagged isFreshTail=true regardless of query match. Useful for "what did I just see" continuity. Capped at 200.',
-                },
-                fresh_tail_session_id: {
-                    type: 'string',
-                    description: 'Restrict the fresh-tail window to a specific session. Without this, fresh-tail is tenant-wide (legacy v1.5.2 behaviour, pre-v1.6.3 default).',
-                },
-                summarize_overflow: {
-                    type: 'boolean',
-                    description: 'When true (default), entries that overflow the limit and share a level-2 parent summary cause that summary to be appended in their place. Set false for strict-limit behaviour.',
-                },
-                scorer_window: {
-                    type: 'number',
-                    description: 'How many of the top-ranked memories the fresh-tail and summarize-overflow appendix is worked out against. The main list ranks the whole tenant store, so scorer_window does not narrow it. Default 200. Rejected as RecallContractError code=invalid_scorer_window if 0/negative/non-finite/non-numeric.',
-                },
-                session_id: {
-                    type: 'string',
-                    maxLength: 256,
-                    description: 'Optional session id (v1.7.4). When set AND (tenant, session) has active goals, applies the dlPFC goal-stack boost to the ranked memories before formatting. Mirrors fresh_tail_session_id shape (256-char cap).',
-                },
-            },
-            required: ['query'],
-        },
-    },
-    {
-        name: 'hippo_assemble',
-        description: 'Build a chronologically-ordered context window for a session. Returns ordered items: fresh-tail raw rows + level-2 summary substitutions for older rows + budget-fit. Hippo-additive vs lossless-claw: eviction picks lowest-strength non-fresh-tail items first instead of oldest-first. Tenant-scoped; default-deny on private scopes.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                session_id: {
-                    type: 'string',
-                    description: 'Session identifier. Returns clean empty result if no kind=raw rows match.',
-                },
-                budget: {
-                    type: 'number',
-                    minimum: 0,
-                    maximum: MAX_BUDGET_TOKENS,
-                    description: `Token budget for the assembled context (default 4000; max ${MAX_BUDGET_TOKENS}). Eviction kicks in over budget.`,
-                },
-                fresh_tail_count: {
-                    type: 'number',
-                    description: 'Recent raw rows always kept verbatim (default 10). These are never evicted.',
-                },
-                summarize_older: {
-                    type: 'boolean',
-                    description: 'When true (default), older raws sharing a level-2 parent summary get substituted. Set false to keep every older raw as-is.',
-                },
-                scope: {
-                    type: 'string',
-                    description: 'Restrict to memories whose scope matches exactly. When omitted, default-deny applies to ANY <source>:private:* scope and unknown:legacy rows. Pass an explicit scope to assemble a private session with consent.',
-                },
-            },
-            required: ['session_id'],
-        },
-    },
-    {
-        name: 'hippo_drill',
-        description: 'Walk one step down the DAG from a level-2+ topic summary to its direct children. Companion to hippo_recall: when recall returns an item with isSummary=true and substitutedFor=[ids], pass the summary id here to recover the original detail. Tenant-scoped; default-deny on private scopes.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                summary_id: {
-                    type: 'string',
-                    description: 'ID of the level-2 (or higher) summary to drill into. Must be a summary, not a leaf — leaves are not drillable.',
-                },
-                limit: {
-                    type: 'number',
-                    minimum: 0,
-                    maximum: MAX_LIST_LIMIT,
-                    description: `Max children to return (default 50; max ${MAX_LIST_LIMIT}).`,
-                },
-                budget: {
-                    type: 'number',
-                    minimum: 0,
-                    maximum: MAX_BUDGET_TOKENS,
-                    description: `Max total token cost (~ chars/4) of returned children (max ${MAX_BUDGET_TOKENS}). Truncates chronologically.`,
-                },
-                depth: {
-                    type: 'integer',
-                    minimum: 1,
-                    maximum: 10,
-                    description: 'v0.30 / E5: walk N levels down (default 1 = direct children only). Higher values include children of children. Token budget remains GLOBAL across levels. Hard cap 10.',
-                },
-            },
-            required: ['summary_id'],
-        },
-    },
-    {
-        name: 'hippo_remember',
-        description: 'Store a new memory. Use when you learn something non-obvious, hit an error, or discover a useful pattern. Memories decay over time unless retrieved. Errors get 2x half-life.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                text: {
-                    type: 'string',
-                    description: 'The memory to store (1-2 sentences, specific and concrete)',
-                },
-                error: { type: 'boolean', description: 'Mark as error memory (doubles half-life)' },
-                pin: { type: 'boolean', description: 'Pin memory (never decays)' },
-                tag: { type: 'string', description: 'Optional tag for categorization' },
-            },
-            required: ['text'],
-        },
-    },
-    {
-        name: 'hippo_outcome',
-        description: 'Report whether recalled memories were useful. Strengthens good memories (+5 days half-life) and weakens bad ones (-3 days). Call after completing work.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                good: {
-                    type: 'boolean',
-                    description: 'true = memories helped, false = memories were irrelevant',
-                },
-            },
-            required: ['good'],
-        },
-    },
-    {
-        name: 'hippo_context',
-        description: 'Smart context injection: auto-detects current task from git state and returns relevant memories plus the active task snapshot, session handoff and recent session trail (the same bundle as GET /v1/context). Use at the start of any session. Memories and those sections are scope-filtered: a no-scope caller does NOT see ANY <source>:private:* (slack, github, ...) or legacy-quarantine rows.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                budget: {
-                    type: 'number',
-                    minimum: 0,
-                    maximum: MAX_BUDGET_TOKENS,
-                    description: `Max tokens (default: config.defaultContextBudget, 3000; max ${MAX_BUDGET_TOKENS})`,
-                },
-                scope: {
-                    type: 'string',
-                    description: 'Restrict memories, snapshot, handoff and trail to this scope exactly. When omitted, default-deny applies to ANY <source>:private:* (slack, github, ...) and unknown-legacy rows.',
-                },
-            },
-        },
-    },
-    {
-        name: 'hippo_status',
-        description: 'Check memory health: counts, strengths, at-risk memories, last consolidation time.',
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-    },
-    {
-        name: 'hippo_learn',
-        description: 'Scan recent git commits for lessons from fix/revert/bug/refactor/perf patterns. Run after coding sessions.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                days: { type: 'number', description: 'Days to scan back (default: 7)' },
-            },
-        },
-    },
-    {
-        name: 'hippo_conflicts',
-        description: 'List open memory conflicts — contradictory memories that need resolution.',
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-    },
-    {
-        name: 'hippo_resolve',
-        description: 'Resolve a memory conflict by keeping one memory and weakening or deleting the other.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                conflict_id: { type: 'number', description: 'The conflict ID to resolve' },
-                keep: { type: 'string', description: 'ID of the memory to keep' },
-                forget: { type: 'boolean', description: 'Delete the loser instead of weakening (default: false)' },
-                rejectLoser: { type: 'boolean', description: 'Tombstone the loser\'s value too, so it refuses re-ingestion (implies removal; default: false)' },
-                reason: { type: 'string', description: 'Reason recorded on the tombstone when rejectLoser is set (default: a conflict-context string)' },
-            },
-            required: ['conflict_id', 'keep'],
-        },
-    },
-    {
-        name: 'hippo_share',
-        description: 'Share a memory to the global store for cross-project use with transfer scoring.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                id: { type: 'string', description: 'Memory ID to share' },
-                force: { type: 'boolean', description: 'Share even if transfer score is low' },
-            },
-            required: ['id'],
-        },
-    },
-    {
-        name: 'hippo_peers',
-        description: 'List all projects that have contributed memories to the global shared store.',
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-    },
-    {
-        name: 'hippo_predict_baserate',
-        description: 'J3 reference-class / planning-fallacy detector. Get base-rate stats for closed predictions in a class. Call this when you make a forward-looking claim (effort estimate, rollout risk, deadline) to anchor on the past track record rather than the inside view. Returns count + mean estimate + mean actual + mean ratio + median ratio + MAE + a human-readable summary. Tenant-scoped.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                class_tag: {
-                    type: 'string',
-                    description: 'Cohort label, e.g. "migration-effort", "rollout-risk", "deadline-week". Must match the class_tag used when the predictions were created via hippo_predict (or `hippo predict ...`).',
-                },
-            },
-            required: ['class_tag'],
-        },
-    },
-];
-const TOOLS_BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));
-// api.retrieve rejects these itself, so MCP and HTTP callers get the same typed error code for the same bad value.
-const ARGS_CHECKED_BY_API = new Map([['hippo_recall', new Set(['scorer_window'])]]);
-// ── Track last recalled IDs for outcome feedback ──
-//
-// Keyed per-client so two HTTP-MCP clients hitting the same tenant cannot
-// poison each other's outcome feedback. The key is `ctx.clientKey` when the
-// transport supplies one (HTTP-MCP via src/server.ts builds
-// hash(bearer+remoteAddr)); stdio and any caller without a clientKey falls
-// back to `'stdio-${pid}'` (one process = one client) or
-// `${tenantId}:default` if a McpContext is constructed in tests without a
-// pid-bound transport.
-const lastRecalledIds = new Map();
-const autoSleepInFlight = new Set();
-function resolveClientKey(ctx) {
-    if (ctx?.clientKey)
-        return ctx.clientKey;
-    if (ctx?.tenantId)
-        return `stdio-${process.pid}:${ctx.tenantId}`;
-    return `stdio-${process.pid}:default`;
-}
-/**
- * Zero-install first run (`npx -y hippo-memory mcp` with no store anywhere):
- * create the global store instead of failing every tool call, and say so on
- * stderr (stdout carries the protocol). `hippo init` in a project later adds
- * a project store, which then 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 (ROADMAP TE0) ──
-const MCP_TOKEN_SURFACES = new Map([
-    ['hippo_recall', 'mcp_recall'],
-    ['hippo_context', 'mcp_context'],
-]);
-/**
- * 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) {
-    const surface = MCP_TOKEN_SURFACES.get(toolName);
-    if (!surface || !output)
-        return;
-    try {
-        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);
-        }
-    }
-    catch {
-        // Ledger is best-effort.
-    }
-}
-// ── Tool execution ──
-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
-    // from the Bearer token (or the loopback fallback). The stdio path
-    // continues to walk from cwd / fall back to the global root, and to
-    // resolve tenant from HIPPO_TENANT.
-    const hippoRoot = ctx?.hippoRoot ?? findHippoRoot() ?? createGlobalStoreOnFirstRun();
-    const config = loadConfig(hippoRoot);
-    // A5: every store read in this server returns to the caller and is
-    // 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({});
-    switch (name) {
-        case 'hippo_recall': {
-            const query = String(args.query || '');
-            const budget = Number(args.budget) || config.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 256-char cap as fresh_tail_session_id.
-            const sessionIdRaw = isJsonString(args.session_id) ? args.session_id.trim() : '';
-            const sessionId = sessionIdRaw.length > 0 && sessionIdRaw.length <= 256
-                ? sessionIdRaw
-                : undefined;
-            const apiCtx = {
-                hippoRoot,
-                tenantId,
-                actor: mcpActor(ctx),
-            };
-            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;
-            const anchorRing = biasHintEnabled('anchoring') && sessionId
-                ? getOrCreateRing(sessionRecallHistoryMcp, buildSessionKey(tenantId, sessionId))
-                : null;
-            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,
-                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,
-                ...recallExtra,
-                showRanked: ({ 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;
-                    };
-                    const planPiece = planningSection(apiResult);
-                    const showPlan = planPiece !== '' && pays(planPiece);
-                    const tailRows = apiResult.results.filter((r) => r.isFreshTail || r.isSummary);
-                    const showTail = tailRows.length > 0 && pays(tailSection(tailRows));
-                    const continuityPiece = includeContinuity && apiResult.continuity ? `\n\n${formatContinuityBlock(apiResult.continuity)}` : '';
-                    const showContinuity = continuityPiece !== '' && pays(continuityPiece);
-                    // J1, J2 and C5: 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 = 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;
-                        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 = buildSuppressionSummary({
-                            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.
-                        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`;
-                        if (showPlan)
-                            text += planPiece;
-                        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) {
-                            text += `## Cutoff\nShowing ${list.length} of ${s.totalCandidates} candidates; ${cutoffClauses.join('; ')}.\n\n---\n\n`;
-                        }
-                        // The window band's fresh-tail and summary rows follow the ranked list, or the MCP fields go unanswered.
-                        text += formatMemories(list) + tailSection(tail) + (showContinuity ? continuityPiece : '');
-                        return { anchoring, availability, text, list };
-                    };
-                    let results = fitBudget(ranked, Math.max(0, left), 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) > budget) {
-                        results = results.slice(0, -1);
-                        rendered = render(results);
-                    }
-                    out.rendered = rendered;
-                    return rendered.list.map((r) => r.entry.id);
-                },
-            });
-            if (!out.rendered)
-                throw new Error('hippo_recall: api.retrieve returned without calling showRanked');
-            const { anchoring: mcpAnchoringHint, availability: mcpAvailabilityHint, list: shown, text: recallText } = out.rendered;
-            lastRecalledIds.set(resolveClientKey(ctx), shown.map((r) => r.entry.id));
-            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') {
-                        const dbForAudit = openHippoDb(hippoRoot);
-                        try {
-                            appendAuditEvent(dbForAudit, {
-                                tenantId,
-                                actor: ctx?.actor ?? 'mcp',
-                                op: 'recall_anchor_detected_memory_dominance',
-                                targetId: mcpAnchoringHint.memoryId,
-                                metadata: {
-                                    memory_id: mcpAnchoringHint.memoryId,
-                                    query_count: mcpAnchoringHint.queryCount ?? null,
-                                },
-                            });
-                        }
-                        finally {
-                            closeHippoDb(dbForAudit);
-                        }
-                    }
-                    else if (mcpAnchoringHint?.reason === 'query_repeat') {
-                        const dbForAudit = openHippoDb(hippoRoot);
-                        try {
-                            appendAuditEvent(dbForAudit, {
-                                tenantId,
-                                actor: ctx?.actor ?? 'mcp',
-                                op: 'recall_anchor_detected_query_repeat',
-                                targetId: mcpAnchoringHint.memoryId,
-                                metadata: { memory_id: mcpAnchoringHint.memoryId },
-                            });
-                        }
-                        finally {
-                            closeHippoDb(dbForAudit);
-                        }
-                    }
-                }
-                else {
-                    // Telemetry: caller had no sessionId so ring tracking skipped.
-                    // Per the recall-audit convention at api.ts:854, use SHA-256/16
-                    // for prompt hashing (NOT hashQueryText which is FNV-1a 32-bit
-                    // for recall matching; brute-force trivial for low-entropy
-                    // queries). Codex round-2 P2 catch.
-                    const dbForAudit = openHippoDb(hippoRoot);
-                    try {
-                        appendAuditEvent(dbForAudit, {
-                            tenantId,
-                            actor: ctx?.actor ?? 'mcp',
-                            op: 'recall_anchor_skipped_no_session',
-                            targetId: undefined,
-                            metadata: auditQueryFields(query),
-                        });
-                    }
-                    finally {
-                        closeHippoDb(dbForAudit);
-                    }
-                }
-            }
-            if (mcpAvailabilityHint) {
-                const dbForAudit = openHippoDb(hippoRoot);
-                try {
-                    appendAuditEvent(dbForAudit, {
-                        tenantId,
-                        actor: ctx?.actor ?? 'mcp',
-                        op: 'recall_availability_detected',
-                        metadata: {
-                            recent_fraction: mcpAvailabilityHint.recentFraction,
-                            older_passed_over: mcpAvailabilityHint.olderCandidatesPassedOver,
-                            returned_count: mcpAvailabilityHint.returnedCount,
-                        },
-                    });
-                }
-                finally {
-                    closeHippoDb(dbForAudit);
-                }
-            }
-            return recallText;
-        }
-        case 'hippo_assemble': {
-            const sessionId = String(args.session_id || '');
-            if (!sessionId)
-                return 'No session_id provided.';
-            const budget = Number(args.budget);
-            const freshTailCount = Number(args.fresh_tail_count);
-            const summarizeOlder = args.summarize_older !== false;
-            const apiCtx = {
-                hippoRoot,
-                tenantId,
-                actor: mcpActor(ctx),
-            };
-            const explicitScope = isJsonString(args.scope) && args.scope.length > 0
-                ? args.scope
-                : undefined;
-            const assembleExtra = {};
-            if (Number.isFinite(budget) && budget > 0)
-                assembleExtra.budget = budget;
-            if (Number.isFinite(freshTailCount) && freshTailCount >= 0)
-                assembleExtra.freshTailCount = freshTailCount;
-            if (explicitScope !== undefined)
-                assembleExtra.scope = explicitScope;
-            const r = apiAssemble(apiCtx, sessionId, {
-                summarizeOlder,
-                ...assembleExtra,
-                cost: assembleCost(sessionId),
-            });
-            return assembleText(r);
-        }
-        case 'hippo_drill': {
-            const summaryId = String(args.summary_id || '');
-            if (!summaryId)
-                return 'No summary_id provided.';
-            const limit = Number(args.limit);
-            const budget = Number(args.budget);
-            // The inputSchema rejects a depth outside 1..10 before this runs, so no silent clamp hides the cap.
-            const depth = args.depth === undefined ? undefined : Number(args.depth);
-            const apiCtx = {
-                hippoRoot,
-                tenantId,
-                actor: mcpActor(ctx),
-            };
-            const drillExtra = {};
-            if (Number.isFinite(limit) && limit > 0)
-                drillExtra.limit = limit;
-            if (Number.isFinite(budget) && budget > 0)
-                drillExtra.budget = budget;
-            if (depth !== undefined)
-                drillExtra.depth = depth;
-            const r = apiDrillDown(apiCtx, summaryId, { ...drillExtra, cost: drillCost });
-            if ('failure' in r) {
-                // v1.6.4: only not_drillable is caller-actionable. not_found
-                // intentionally collapses cross-tenant + scope-blocked + missing
-                // (codex round 3 P1: distinguishing scope_blocked would leak
-                // private-row existence on this surface).
-                if (r.failure === 'not_drillable') {
-                    return `Id ${summaryId} is a leaf row, not a level-2+ summary; nothing to drill into.`;
-                }
-                return `No drillable summary at id=${summaryId}.`;
-            }
-            return drillText(r);
-        }
-        case 'hippo_predict_baserate': {
-            // J3 reference-class / planning-fallacy detector. Reads from the E2
-            // predictions table; returns text-only response matching the existing
-            // MCP tool convention (no structured JSON over the wire). Direct call
-            // to computePredictionBaserate; helper opens its own db + emits audit
-            // (single source of truth, no caller-site drift).
-            const classTag = String(args.class_tag || '').trim();
-            if (!classTag)
-                return 'No class_tag provided. Usage: pass class_tag matching a class used in past predictions (e.g. "migration-effort").';
-            const baserate = computePredictionBaserate(hippoRoot, tenantId, classTag, ctx?.actor ?? 'mcp');
-            if (baserate.nClosed === 0) {
-                return `No closed predictions in class "${classTag}" yet. Create one via hippo_predict (or 'hippo predict ...' CLI) and close it with hippo_predict_close once the actual outcome is known. Base rates need closed predictions with numeric actual_value to compute.`;
-            }
-            const lines = [baserate.summary, ''];
-            lines.push(`n_closed:         ${baserate.nClosed}`);
-            lines.push(`n_ratio_eligible: ${baserate.nRatioEligible}`);
-            if (baserate.meanEstimate !== null)
-                lines.push(`mean_estimate:    ${baserate.meanEstimate.toFixed(3)}`);
-            if (baserate.meanActual !== null)
-                lines.push(`mean_actual:      ${baserate.meanActual.toFixed(3)}`);
-            if (baserate.meanRatio !== null)
-                lines.push(`mean_ratio:       ${baserate.meanRatio.toFixed(3)}x`);
-            if (baserate.p50Ratio !== null)
-                lines.push(`p50_ratio:        ${baserate.p50Ratio.toFixed(3)}x`);
-            if (baserate.mae !== null)
-                lines.push(`mae:              ${baserate.mae.toFixed(3)}`);
-            return lines.join('\n');
-        }
-        case 'hippo_remember': {
-            const text = String(args.text || '');
-            if (!text)
-                return 'No text provided.';
-            const tags = [];
-            if (args.error)
-                tags.push('error');
-            if (args.tag)
-                tags.push(String(args.tag));
-            // Route through api.ts so audit_log captures the caller identity
-            // uniformly with CLI/REST: the auth-resolved ctx.actor under HTTP-MCP,
-            // 'mcp' for stdio (no ctx). api.ts.remember writes the memory + audit
-            // row in one transaction-friendly path; we re-read the entry to surface
-            // the half-life used in the MCP human-readable response.
-            const apiCtx = {
-                hippoRoot,
-                tenantId,
-                actor: mcpActor(ctx),
-            };
-            const result = apiRemember(apiCtx, {
-                content: text,
-                tags,
-            });
-            const entry = readEntry(hippoRoot, result.id, tenantId);
-            // Auto-sleep: one run per store at a time, triggered by what arrived since the last one.
-            if (config.autoSleep.enabled &&
-                !autoSleepInFlight.has(hippoRoot) &&
-                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)
-                    .catch((err) => {
-                    log.error(`auto-sleep consolidate failed (tenant ${tenantId}): ${err instanceof Error ? err.message : String(err)}`);
-                })
-                    .finally(() => autoSleepInFlight.delete(hippoRoot));
-            }
-            const halfLife = entry?.half_life_days ?? config.defaultHalfLifeDays;
-            const tagStr = entry?.tags.join(', ') || tags.join(', ') || 'none';
-            const warnings = (result.warnings ?? []).map((w) => `\nWarning: ${w}`).join('');
-            return `Remembered [${result.id}] (half-life: ${halfLife}d, tags: ${tagStr})${warnings}`;
-        }
-        case 'hippo_outcome': {
-            const good = Boolean(args.good);
-            const clientKey = resolveClientKey(ctx);
-            const ids = lastRecalledIds.get(clientKey) ?? [];
-            if (ids.length === 0)
-                return 'No recent recalls to apply outcome to.';
-            // Route through src/api.ts so audit_log captures the caller identity
-            // (auth-resolved ctx.actor under HTTP-MCP, 'mcp' for stdio) and tenant
-            // scoping is enforced uniformly (same surface as recall/remember).
-            // outcome() also handles cross-tenant id skip silently.
-            const apiCtx = {
-                hippoRoot,
-                tenantId,
-                actor: mcpActor(ctx),
-            };
-            const { applied } = apiOutcome(apiCtx, ids, good);
-            return `Applied ${good ? 'positive' : 'negative'} outcome to ${applied} memories`;
-        }
-        case 'hippo_context': {
-            const budget = args.budget === undefined
-                ? config.defaultContextBudget
-                : Number(args.budget);
-            if (!Number.isFinite(budget) || budget < 0)
-                return 'budget must be a non-negative number.';
-            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;
-            // The served store names the project (an HTTP daemon runs from anywhere); the global root names none, so stdio falls back to its launch cwd.
-            const storeProject = resolveProjectIdentity(path.dirname(path.resolve(hippoRoot))).name;
-            const result = await apiGetContext({ hippoRoot, tenantId, actor: mcpActor(ctx) }, {
-                q: autoDetectContext(),
-                budget,
-                exactScope,
-                currentProject: storeProject !== '' ? storeProject : resolveProjectIdentity(process.cwd()).name,
-                cost: contextCost,
-            });
-            lastRecalledIds.set(resolveClientKey(ctx), result.entries.map((r) => r.entry.id));
-            return (result.activeSnapshot ? snapshotPiece(result.activeSnapshot) : '')
-                + (result.sessionHandoff ? handoffPiece(result.sessionHandoff) : '')
-                + (result.recentEvents ? trailPiece(result.recentEvents) : '')
-                + formatMemories(result.entries);
-        }
-        case 'hippo_status': {
-            // Every row counts toward the averages, so this scans the store, but without its text.
-            const entries = loadStrengthRows(hippoRoot, tenantId);
-            const now = evalNow(); // honors HIPPO_FAKE_NOW (eval-only; see ablation.ts)
-            let atRisk = 0;
-            let totalStrength = 0;
-            for (const e of entries) {
-                const s = calculateStrength(e, now);
-                totalStrength += s;
-                if (s < 0.1 && !e.pinned)
-                    atRisk++;
-            }
-            const avgStrength = entries.length > 0 ? (totalStrength / entries.length).toFixed(2) : '0';
-            const pinned = entries.filter((e) => e.pinned).length;
-            const errors = entries.filter((e) => e.tags.includes('error')).length;
-            const conflicts = listMemoryConflicts(hippoRoot, 'open', tenantId).length;
-            return [
-                `Memories: ${entries.length} (${pinned} pinned, ${errors} errors)`,
-                `Avg strength: ${avgStrength}`,
-                `At risk (<0.1): ${atRisk}`,
-                `Open conflicts: ${conflicts}`,
-                `Half-life default: ${config.defaultHalfLifeDays}d`,
-            ].join('\n');
-        }
-        case 'hippo_learn': {
-            const days = Number(args.days) || 7;
-            if (!isGitRepo(process.cwd()))
-                return 'No git history found.';
-            const gitLog = fetchGitLog(process.cwd(), days);
-            if (!gitLog.trim())
-                return 'No fix/revert/bug commits found in the specified period.';
-            const parsedLessons = extractLessons(gitLog, config.gitLearnPatterns);
-            // DF4: admission gate lives at the write path, not in extractLessons
-            // (a published API surface that only parses). Bare subjects like
-            // "fixed signals" are dropped here, before they ever become a memory.
-            // Gating the loop INPUT is correct here, unlike the CLI path: this
-            // loop only writes. The CLI's loop also runs invalidation, so there
-            // the gate has to sit on the write alone or a migration subject stops
-            // superseding stale memories. Same predicate, different placement,
-            // because the loops do different work.
-            const { kept: lessons, dropped } = partitionLessons(parsedLessons);
-            const lowInfo = dropped.length;
-            let added = 0;
-            let skipped = 0;
-            let rejected = 0;
-            const keys = storedTextKeys(loadTextsHoldingWords(hippoRoot, tenantId, lessons.map(longestWord)));
-            for (const lesson of lessons) {
-                if (keys.has(duplicateKey(lesson))) {
-                    skipped++;
-                    continue;
-                }
-                const entry = createMemory(lesson, {
-                    layer: Layer.Episodic,
-                    tags: ['git-learned'],
-                    source: 'git',
-                    confidence: 'observed',
-                    baseHalfLifeDays: config.defaultHalfLifeDays,
-                    tenantId,
-                });
-                // AT1 (plan §3 containment): a refused lesson must not crash the
-                // MCP learn call or lose the rest of the git log scan.
-                try {
-                    writeEntry(hippoRoot, entry, { actor: ctx?.actor ?? 'mcp' });
-                }
-                catch (err) {
-                    if (err instanceof RejectedValueError) {
-                        rejected++;
-                        continue;
-                    }
-                    throw err;
-                }
-                keys.add(duplicateKey(lesson));
-                added++;
-            }
-            const rejectedSuffix = rejected > 0 ? `, ${rejected} rejected values skipped` : '';
-            const lowInfoSuffix = lowInfo > 0 ? `, ${lowInfo} low-information subjects dropped` : '';
-            return `Git learn: ${added} new, ${skipped} duplicates skipped${rejectedSuffix}${lowInfoSuffix} (scanned ${days} days)`;
-        }
-        case 'hippo_conflicts': {
-            const conflicts = listMemoryConflicts(hippoRoot, 'open', tenantId);
-            if (conflicts.length === 0)
-                return 'No open conflicts.';
-            return conflicts.map((c) => `conflict_${c.id}: ${c.memory_a_id} <-> ${c.memory_b_id} (score=${c.score.toFixed(2)}) — ${c.reason}`).join('\n');
-        }
-        case 'hippo_resolve': {
-            const conflictId = Number(args.conflict_id);
-            const keepId = String(args.keep || '');
-            const forget = Boolean(args.forget);
-            // AT1: optional rejectLoser + reason, threaded straight through to
-            // resolveConflict's opts (plan §5 — mirrors the CLI's --reject-loser).
-            const rejectLoser = Boolean(args.rejectLoser);
-            const reason = isJsonString(args.reason) ? args.reason : undefined;
-            if (isNaN(conflictId) || !keepId)
-                return 'Required: conflict_id and keep.';
-            const result = resolveConflict(hippoRoot, conflictId, keepId, forget, tenantId, {
-                rejectLoserValue: rejectLoser,
-                reason,
-                // P2 fix: resolveConflict's opts.rejectedBy defaults to 'cli' when
-                // omitted — this call site never passed it, so the tombstone's
-                // rejected_by AND the conflict_resolve audit's actor both landed as
-                // 'cli' even though the caller was MCP. ctx.actor carries the
-                // auth-resolved actor for HTTP-MCP (see McpContext above); stdio
-                // callers pass no ctx, so 'mcp' is the honest fallback there.
-                rejectedBy: ctx?.actor ?? 'mcp',
-            });
-            if (!result)
-                return 'Could not resolve. Check the conflict ID and --keep value.';
-            const action = rejectLoser ? 'rejected (tombstoned) and removed' : forget ? 'deleted' : 'weakened';
-            return `Resolved conflict ${conflictId}: kept ${keepId}, ${action} ${result.loserId}`;
-        }
-        case 'hippo_share': {
-            const shareId = String(args.id || '');
-            if (!shareId)
-                return 'Required: id (memory ID to share).';
-            const force = Boolean(args.force);
-            // Pass tenantId so shareMemory's readEntry filters by tenant. Without
-            // this, a Bearer for tenant A could call hippo_share with tenant B's
-            // id and copy the row to the global store. The 'Memory not found'
-            // error matches the cross-tenant deny shape elsewhere in the code.
-            const shared = shareMemory(hippoRoot, shareId, { force, tenantId });
-            if (!shared)
-                return 'Transfer score too low. Use force=true to override.';
-            return `Shared [${shared.id}] to global store. Source: ${shared.source}`;
-        }
-        case 'hippo_peers': {
-            // D4 v1.12.10: tenant-scope the cross-project peer discovery.
-            // tenantId is the caller's tenant (matches hippo_share above);
-            // passing undefined would restore the pre-D4 host-wide behaviour.
-            const peers = listPeers(undefined, tenantId);
-            if (peers.length === 0)
-                return 'No peers found.';
-            return peers.map((p) => `${p.project}: ${p.count} memories (latest: ${p.latest.slice(0, 10)})`).join('\n');
-        }
-        default:
-            // handleMcpRequest rejects names missing from TOOLS, so reaching here means TOOLS and this switch drifted apart.
-            throw new Error(`hippo-mcp: tool ${name} is declared but has no handler`);
-    }
-}
-// ── Request handling ──
-/**
- * Transport-agnostic MCP dispatcher. Both the stdio loop (below) and the
- * HTTP/SSE transport in src/server.ts route every incoming JSON-RPC message
- * through this single function. Returns null for notifications (no response
- * expected) and a McpResponse otherwise. Errors thrown by `executeTool` are
- * the caller's problem — wrap with try/catch on the transport side.
- */
-export async function handleMcpRequest(req, ctx) {
-    const { id, method, params } = req;
-    switch (method) {
-        case 'initialize':
-            return {
-                jsonrpc: '2.0',
-                id,
-                result: {
-                    protocolVersion: '2024-11-05',
-                    capabilities: { tools: {} },
-                    serverInfo: { name: 'hippo-memory', version: PACKAGE_VERSION },
-                },
-            };
-        case 'notifications/initialized':
-            return null;
-        case 'tools/list':
-            return { jsonrpc: '2.0', id, result: { tools: TOOLS } };
-        case 'tools/call': {
-            const nameValue = params?.name;
-            const toolName = isJsonString(nameValue) ? nameValue : '';
-            const tool = TOOLS_BY_NAME.get(toolName);
-            if (!tool) {
-                return { jsonrpc: '2.0', id, error: { code: -32602, message: `Unknown tool: ${toolName.slice(0, 128)}` } };
-            }
-            const argumentsValue = params?.arguments;
-            if (argumentsValue !== undefined && argumentsValue !== null && !isJsonObjectRecord(argumentsValue)) {
-                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 },
-                };
-            }
-            const output = await executeTool(toolName, toolArgs, ctx);
-            recordMcpTokens(toolName, output, ctx);
-            return {
-                jsonrpc: '2.0',
-                id,
-                result: {
-                    content: [{ type: 'text', text: output || 'Done.' }],
-                },
-            };
-        }
-        default:
-            // Notifications (no id) must not receive a response
-            if (method.startsWith('notifications/'))
-                return null;
-            return {
-                jsonrpc: '2.0',
-                id,
-                error: { code: -32601, message: `Method not found: ${method}` },
-            };
-    }
-}
-// ── Stdio transport ──
-import { parseFrame } from './framing.js';
-let buffer = Buffer.alloc(0);
-function dispatch(body) {
-    let req;
-    try {
-        // SAFETY: malformed JSON is caught below and the frame is skipped; the
-        // JSON-RPC shape itself is validated field-by-field next (req.method
-        // truthiness check), matching the src/server.ts HTTP transport's own
-        // `JSON.parse(raw) as McpRequest` boundary cast.
-        req = JSON.parse(body);
-    }
-    catch {
-        log.debug('mcp: skipped a frame that is not valid JSON');
-        return;
-    }
-    if (!req.method)
-        return;
-    if (req.method.startsWith('notifications/')) {
-        handleMcpRequest(req).catch((err) => {
-            log.error(`mcp notification ${req.method} failed: ${err instanceof Error ? err.message : String(err)}`);
-        });
-        return;
-    }
-    handleMcpRequest(req).then((resp) => { if (resp)
-        send(resp); }).catch((err) => {
-        send(mcpErrorResponse(req.id, err));
-    });
-}
-/**
- * Wire stdin/stdout to the dispatcher. Idempotent — only the entrypoint
- * (cli.ts `hippo mcp`, or running this file directly) should call this.
- * src/server.ts imports `handleMcpRequest` without invoking this, so the
- * HTTP daemon does not steal stdin or exit when its parent closes a pipe.
- */
-export function startStdioLoop() {
-    process.stdin.on('data', (chunk) => {
-        buffer = Buffer.concat([buffer, chunk]);
-        while (true) {
-            const result = parseFrame(buffer);
-            if (result.kind === 'incomplete')
-                break;
-            buffer = result.rest;
-            if (result.kind === 'message')
-                dispatch(result.body);
-        }
-    });
-    process.stdin.on('end', () => process.exit(0));
-    process.on('uncaughtException', (err) => {
-        log.error(`mcp uncaught: ${err instanceof Error ? err.message : String(err)}`);
-    });
-    process.on('unhandledRejection', (err) => {
-        log.error(`mcp unhandled: ${err instanceof Error ? err.message : String(err)}`);
-    });
-}
+export { __resetSessionRecallHistoryMcp } from './session-state.js';
+export { findHippoRoot, mcpErrorResponse } from './protocol.js';
+export { handleMcpRequest } from './request.js';
+export { startStdioLoop } from './stdio.js';
+import { envMcpStdio } from '../env.js';
+import { startStdioLoop } from './stdio.js';
 // Auto-start when invoked as the main module (node dist/mcp/server.js or via
 // the cli's `import('./mcp/server.js')`). Importing this file from another
 // module (e.g. src/server.ts wiring up the HTTP/SSE transport) will NOT
@@ -1208,7 +25,7 @@ const isMainModule = (() => {
         const argv1 = process.argv[1] ?? '';
         if (argv1.endsWith('mcp/server.js') || argv1.endsWith('mcp\\server.js'))
             return true;
-        if (process.env.HIPPO_MCP_STDIO === '1')
+        if (envMcpStdio())
             return true;
         // ESM main-module check
         const mainUrl = `file://${argv1.replace(/\\/g, '/')}`;