hippo-memory 1.69.0 → 1.71.0

package/dist/mcp/request.js

@@ -1,28 +1,24 @@
 // Transport-agnostic request handling: tool dispatch table, tool execution and the JSON-RPC method switch.
-import { log } from '../log.js';
-import { STORE_NOT_PORTED_MESSAGE } from '../http-util.js';
-import { getGlobalRoot, initGlobal } from '../shared.js';
-import { loadConfig } from '../config.js';
-import { resolveTenantId } from '../tenant.js';
-import { rethrowIfSqliteBlocked, runWithRequestStores } from '../db.js';
-import { hasGroup, storeFor } from '../store-port.js';
-import { estimateTokens } from '../token-ledger.js';
-import { PACKAGE_VERSION } from '../version.js';
+import { errorMessage, log } from '../util/log.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 { rethrowIfSqliteBlocked, runWithRequestStores } from '../db/index.js';
+import { hasGroup, storeFor } 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, isJsonObjectRecord } from './protocol.js';
+import { findHippoRoot } 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 { sharedStoreRefusal } from './shared-gate.js';
-import { isJsonString } from '../json.js';
-/**
- * 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.
- */
+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();
@@ -34,10 +30,7 @@ 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.
- */
+/** 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)
@@ -56,14 +49,14 @@ export async function recordMcpTokens(toolName, output, ctx) {
     }
     catch (err) {
         rethrowIfSqliteBlocked(err);
-        log.warnThenDebug('mcp-token-ledger', `token ledger write failed; the tool reply is unaffected: ${err instanceof Error ? err.message : String(err)}`);
+        log.warnThenDebug('mcp-token-ledger', `token ledger write failed; the tool reply is unaffected: ${errorMessage(err)}`);
     }
 }
 const TOOL_HANDLERS = new Map([
     ['hippo_recall', { handler: runRecallTool, storeReady: 'base' }],
-    ['hippo_assemble', { handler: runAssembleTool }],
-    ['hippo_drill', { handler: runDrillTool }],
-    ['hippo_predict_baserate', { handler: runPredictBaserateTool }],
+    ['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' }],
@@ -84,16 +77,12 @@ function runsOn(store, toolName) {
     return group !== undefined && hasGroup(store, group);
 }
 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.
+    // 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();
     const config = loadConfig(hippoRoot);
-    // 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.
+    // 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;
     // handleMcpRequest rejects names missing from TOOLS, so reaching here means TOOLS and this table drifted apart.
@@ -110,13 +99,53 @@ function invalidArgs(id, toolName, problems) {
         result: { content: [{ type: 'text', text: `Invalid arguments for ${toolName}: ${problems.join('; ')}` }], isError: true },
     };
 }
-/**
- * Transport-agnostic MCP dispatcher. Both the stdio loop (below) and the
- * HTTP/SSE transport in src/server.ts route every incoming JSON-RPC message
- * 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.
- */
+async function callTool(id, params, ctx) {
+    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)}` } };
+    }
+    // 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)) {
+        return { jsonrpc: '2.0', id, error: { code: -32603, message: STORE_NOT_PORTED_MESSAGE } };
+    }
+    const refusal = sharedStoreRefusal(toolName, ctx);
+    if (refusal !== undefined)
+        return { jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: refusal }], isError: true } };
+    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` } };
+    }
+    const toolArgs = isJsonObject(argumentsValue) ? argumentsValue : {};
+    const problems = validateToolArgs(tool.inputSchema, toolArgs, ARGS_CHECKED_BY_API.get(toolName));
+    if (problems.length > 0)
+        return invalidArgs(id, toolName, problems);
+    let output;
+    try {
+        // One handle per store for the tool and its ledger row; stdio interleaves calls, so each gets its own scope.
+        output = await runWithRequestStores(async () => {
+            const text = await executeTool(toolName, toolArgs, ctx);
+            await recordMcpTokens(toolName, text, ctx);
+            return text;
+        });
+    }
+    catch (err) {
+        if (!(err instanceof RecallRequestError))
+            throw err;
+        return invalidArgs(id, toolName, [err.message]);
+    }
+    return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+            content: [{ type: 'text', text: output || 'Done.' }],
+        },
+    };
+}
+/** 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 async function handleMcpRequest(req, ctx) {
     const { id, method, params } = req;
     switch (method) {
@@ -136,51 +165,8 @@ export async function handleMcpRequest(req, ctx) {
             const other = otherStore(ctx);
             return { jsonrpc: '2.0', id, result: { tools: other ? TOOLS.filter((t) => runsOn(other, t.name)) : 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)}` } };
-            }
-            // 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)) {
-                return { jsonrpc: '2.0', id, error: { code: -32603, message: STORE_NOT_PORTED_MESSAGE } };
-            }
-            const refusal = sharedStoreRefusal(toolName, ctx);
-            if (refusal !== undefined)
-                return { jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: refusal }], isError: true } };
-            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 : {};
-            const problems = validateToolArgs(tool.inputSchema, toolArgs, ARGS_CHECKED_BY_API.get(toolName));
-            if (problems.length > 0)
-                return invalidArgs(id, toolName, problems);
-            let output;
-            try {
-                // One handle per store for the tool and its ledger row; stdio interleaves calls, so each gets its own scope.
-                output = await runWithRequestStores(async () => {
-                    const text = await executeTool(toolName, toolArgs, ctx);
-                    await recordMcpTokens(toolName, text, ctx);
-                    return text;
-                });
-            }
-            catch (err) {
-                if (!(err instanceof RecallRequestError))
-                    throw err;
-                return invalidArgs(id, toolName, [err.message]);
-            }
-            return {
-                jsonrpc: '2.0',
-                id,
-                result: {
-                    content: [{ type: 'text', text: output || 'Done.' }],
-                },
-            };
-        }
+        case 'tools/call':
+            return callTool(id, params, ctx);
         default:
             // Notifications (no id) must not receive a response
             if (method.startsWith('notifications/'))

package/dist/mcp/server.d.ts

@@ -1,13 +1,7 @@
 #!/usr/bin/env node
-/**
- * Hippo Memory MCP Server
- *
- * Exposes hippo memory as MCP tools over stdio transport.
- * Uses the programmatic API directly (no child process spawning).
- *
- * Usage: hippo mcp (or npx hippo-memory mcp)
- */
-export { __resetSessionRecallHistoryMcp } from './session-state.js';
+/** 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';
 export { handleMcpRequest } from './request.js';
 export { startStdioLoop } from './stdio.js';

package/dist/mcp/server.js

@@ -1,25 +1,14 @@
 #!/usr/bin/env node
-/**
- * Hippo Memory MCP Server
- *
- * Exposes hippo memory as MCP tools over stdio transport.
- * Uses the programmatic API directly (no child process spawning).
- *
- * Usage: hippo mcp (or npx hippo-memory mcp)
- */
-export { __resetSessionRecallHistoryMcp } from './session-state.js';
+/** 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';
 export { handleMcpRequest } from './request.js';
 export { startStdioLoop } from './stdio.js';
-import { envMcpStdio } from '../env.js';
+import { envMcpStdio } from '../util/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
-// trigger the stdio loop. The cli imports this file specifically to start
-// stdio; that import is also `import.meta.url === main`-equivalent because
-// it's executed as the program, so we keep a fallback: if HIPPO_MCP_STDIO=1
-// or argv1 ends in /mcp/server.js we start.
+// 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 {
         const argv1 = process.argv[1] ?? '';

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

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

package/dist/mcp/session-state.js

@@ -1,19 +1,13 @@
 // 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';
 /** Test-only: reset the MCP recall rings. Call from beforeEach. */
-export function __resetSessionRecallHistoryMcp() {
+export function _resetSessionRecallHistoryMcpForTests() {
     resetSessionRings('mcp');
 }
-// ── 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.
-export const MAX_RECALL_CLIENTS = 4096;
+// 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.
 class RecentRecalls extends Map {
     set(key, ids) {
@@ -26,9 +20,9 @@ class RecentRecalls extends Map {
     }
 }
 export const lastRecalledIds = new RecentRecalls();
-export const autoSleepInFlight = new Set();
+export { autoSleepInFlight } from '../api/auto-sleep.js';
 export function resolveClientKey(ctx) {
-    const base = ctx?.clientKey ? ctx.clientKey : `stdio-${process.pid}:${ctx?.tenantId || 'default'}`;
+    const base = ctx?.clientKey ? ctx.clientKey : `stdio-${process.pid}:${ctx?.tenantId || DEFAULT_TENANT_ID}`;
     return ctx?.project ? `${base}:${ctx.project.name}` : base;
 }
 //# sourceMappingURL=session-state.js.map

package/dist/mcp/shared-gate.js

@@ -1,5 +1,5 @@
 // Which MCP tools run on a shared store, and which need the caller's project first.
-import { isSharedStore } from '../config.js';
+import { isSharedStore } from '../core/config.js';
 // A shared store holds many repos' rows, so a memory tool needs the caller's project and four tools never run.
 const OFF_ON_SHARED = new Map([
     ['hippo_learn', "reads the server's git history"],

package/dist/mcp/stdio.d.ts

@@ -1,8 +1,4 @@
-/**
- * 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.
- */
+/** Wires stdin/stdout to the dispatcher; idempotent. Only the entrypoint (cli.ts `hippo mcp`, or this file run directly) should call it, so the HTTP daemon
+ * (which imports `handleMcpRequest`) does not steal stdin or exit when its parent closes a pipe. */
 export declare function startStdioLoop(): void;
 //# sourceMappingURL=stdio.d.ts.map

package/dist/mcp/stdio.js

@@ -1,9 +1,13 @@
 // Stdio transport: newline-delimited JSON-RPC frames in on stdin, replies out on stdout.
-import { errorFields, log } from '../log.js';
+import { exitAfterFlush, installCrashHandlers } from '../util/crash-handlers.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
+import { requestDeadlineMs } from '../server/deadline.js';
 import { parseFrame } from './framing.js';
-import { mcpErrorResponse, isJsonObjectRecord } from './protocol.js';
+import { mcpErrorResponse } from './protocol.js';
 import { handleMcpRequest } from './request.js';
-import { isJsonString } from '../json.js';
+import { isJsonNumber, isJsonString, isJsonObject } from '../util/json.js';
+import { randomUUID } from 'node:crypto';
+import { currentRequestId, runWithRequestId } from '../util/request-scope.js';
 // MCP stdio transport spec: messages are newline-delimited JSON-RPC, no embedded newlines.
 // https://modelcontextprotocol.io/specification/.../basic/transports#stdio
 function send(msg) {
@@ -11,9 +15,85 @@ function send(msg) {
 }
 // ── Stdio transport ──
 let buffer = Buffer.alloc(0);
+// The part of a refused frame still on its way, dropped as it arrives so it is never buffered or read as a new frame.
+let refused = 0;
+function withoutRefused(chunk) {
+    if (refused === 'line') {
+        const newline = chunk.indexOf(0x0a);
+        if (newline === -1)
+            return chunk.subarray(chunk.length);
+        refused = 0;
+        return chunk.subarray(newline + 1);
+    }
+    const dropped = Math.min(refused, chunk.length);
+    refused -= dropped;
+    return chunk.subarray(dropped);
+}
 // Only method is checked: handleMcpRequest narrows params where it reads them, as the HTTP transport does.
 function isRoutableRequest(v) {
-    return isJsonObjectRecord(v) && isJsonString(v.method);
+    return isJsonObject(v) && isJsonString(v.method);
+}
+/** A frame that parsed but names no method: with an id it is a request owed an answer; without one it is a notification, which JSON-RPC forbids answering. */
+function answerUnroutable(frame) {
+    const id = isJsonObject(frame) ? frame.id : undefined;
+    if (isJsonString(id) || isJsonNumber(id)) {
+        send({ jsonrpc: '2.0', id, error: { code: -32600, message: 'Invalid Request: method must be a string' } });
+        return;
+    }
+    log.warn('mcp: dropped a frame with no method and no id; it cannot be routed or answered');
+}
+/** How long stdin's end waits for calls still running, so a client that closes right after its last request still gets the reply. */
+const STDIN_END_DRAIN_MS = 5000;
+// Calls dispatched and not yet answered, each with the method the drain names if it is still running at the bound.
+const inFlight = new Map();
+function track(method, call) {
+    inFlight.set(call, method);
+    void call.finally(() => inFlight.delete(call));
+}
+async function exitWhenDrained() {
+    if (inFlight.size > 0) {
+        let bound;
+        const timedOut = new Promise((resolve) => { bound = setTimeout(resolve, STDIN_END_DRAIN_MS); });
+        await Promise.race([Promise.allSettled(inFlight.keys()), timedOut]);
+        clearTimeout(bound);
+    }
+    for (const method of inFlight.values()) {
+        log.warn(`mcp: ${method} was still running ${STDIN_END_DRAIN_MS} ms after stdin closed; exiting without its reply`, { method });
+    }
+    exitAfterFlush(0);
+}
+// The code the MCP SDKs give a request that timed out.
+const REQUEST_TIMEOUT_CODE = -32001;
+/** The method, with the tool's name for a tool call, so a timeout names what ran. */
+function callName(req) {
+    const tool = req.params?.name;
+    return isJsonString(tool) ? `${req.method} ${tool.slice(0, 128)}` : req.method;
+}
+/** Answers `req` with one timeout error at the deadline a served request has. The returned function stops the timer and says whether that answer went out, so a later reply is dropped. */
+function watchDeadline(req, owedReply) {
+    const ms = requestDeadlineMs();
+    if (ms === 0)
+        return () => false;
+    let expired = false;
+    const timer = setTimeout(() => {
+        expired = true;
+        const name = callName(req);
+        log.warn(`mcp: ${name} did not answer within ${ms} ms; it keeps running and its reply will be dropped`, { method: req.method });
+        if (!owedReply)
+            return;
+        const requestId = currentRequestId();
+        const message = `Request timed out: ${name} did not finish within ${ms} ms; a write it started may or may not be saved`;
+        const error = { code: REQUEST_TIMEOUT_CODE, message };
+        if (requestId !== undefined)
+            error.data = { requestId };
+        send({ jsonrpc: '2.0', id: req.id, error });
+    }, ms);
+    // Stdin and the call keep the process alive; this timer alone must not.
+    timer.unref();
+    return () => {
+        clearTimeout(timer);
+        return expired;
+    };
 }
 function dispatch(body) {
     let parsed;
@@ -25,56 +105,50 @@ function dispatch(body) {
         send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
         return;
     }
-    // A frame without a string method cannot be routed; dropping it keeps a stray value from crashing the process.
-    if (!isRoutableRequest(parsed))
+    if (!isRoutableRequest(parsed)) {
+        answerUnroutable(parsed);
         return;
+    }
     const req = parsed;
     if (req.method.startsWith('notifications/')) {
-        handleMcpRequest(req).catch((err) => {
-            log.error(`mcp notification ${req.method} failed: ${err instanceof Error ? err.message : String(err)}`);
-        });
+        const stopWatching = watchDeadline(req, false);
+        track(req.method, handleMcpRequest(req).then(() => { }).catch((err) => {
+            log.error(`mcp notification ${req.method} failed: ${errorMessage(err)}`, errorFields(err));
+        }).finally(stopWatching));
         return;
     }
-    handleMcpRequest(req).then((resp) => { if (resp)
+    // A frame with no id is a notification under any method name, and JSON-RPC forbids answering one.
+    const timedOut = watchDeadline(req, isJsonString(req.id) || isJsonNumber(req.id));
+    track(req.method, handleMcpRequest(req).then((resp) => { if (!timedOut() && resp)
         send(resp); }).catch((err) => {
-        send(mcpErrorResponse(req.id, err));
-    });
+        if (timedOut())
+            log.debug(`mcp: ${callName(req)} failed after its timeout reply: ${errorMessage(err)}`);
+        else
+            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.
- */
+/** Wires stdin/stdout to the dispatcher; idempotent. Only the entrypoint (cli.ts `hippo mcp`, or this file run directly) should call it, so the HTTP daemon
+ * (which imports `handleMcpRequest`) 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]);
+        buffer = Buffer.concat([buffer, withoutRefused(chunk)]);
         while (true) {
             const result = parseFrame(buffer);
             if (result.kind === 'incomplete')
                 break;
             buffer = result.rest;
+            if (result.kind === 'oversize') {
+                refused = result.remainder;
+                log.warn('mcp: refused a frame over the size cap with a parse error');
+                send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error: frame exceeds 1MB' } });
+                continue;
+            }
+            // One id per frame, so the error reply and every line logged for the call name the same request.
             if (result.kind === 'message')
-                dispatch(result.body);
+                runWithRequestId(randomUUID(), () => dispatch(result.body));
         }
     });
-    process.stdin.on('end', () => process.exit(0));
-    // After an uncaught throw the process state is unknown, so log the cause and exit for the client to restart the server.
-    const crash = (kind, err) => {
-        log.error(`mcp ${kind}: ${err instanceof Error ? err.message : String(err)}`, errorFields(err));
-        exitAfterFlush(1);
-    };
-    process.on('uncaughtException', (err) => crash('uncaught exception', err));
-    process.on('unhandledRejection', (err) => crash('unhandled rejection', err));
-}
-/** Exit once stdout and stderr have drained, so the last reply and the crash log reach the client; capped at 1 s. */
-function exitAfterFlush(code) {
-    process.exitCode = code;
-    let pending = 2;
-    const done = () => { if (--pending === 0)
-        process.exit(code); };
-    process.stdout.write('', done);
-    process.stderr.write('', done);
-    setTimeout(() => process.exit(code), 1000).unref();
+    process.stdin.on('end', () => { void exitWhenDrained(); });
+    installCrashHandlers('mcp');
 }
 //# sourceMappingURL=stdio.js.map

package/dist/mcp/tool-args.js

@@ -1,4 +1,5 @@
 // Hand-written for the JSON Schema subset the hippo tool definitions use, so the MCP server needs no validator dependency.
+const ARG_PREVIEW_CHARS = 40;
 function isArgString(v) {
     return typeof v === 'string';
 }
@@ -23,7 +24,7 @@ function describeValue(v) {
     if (Array.isArray(v))
         return 'array';
     if (isArgString(v))
-        return JSON.stringify(v.length > 40 ? `${v.slice(0, 40)}...` : v);
+        return JSON.stringify(v.length > ARG_PREVIEW_CHARS ? `${v.slice(0, ARG_PREVIEW_CHARS)}...` : v);
     if (isArgNumber(v) || isArgBoolean(v))
         return String(v);
     return 'object';

package/dist/mcp/tools.js

@@ -1,7 +1,9 @@
 // Tool definitions and input schemas served by tools/list.
-import { DEFAULT_RECALL_BUDGET } from '../search/types.js';
+import { DEFAULT_RECALL_BUDGET } from '../core/search-types.js';
 import { DEFAULT_ASSEMBLE_BUDGET } from '../api/assemble.js';
-import { MAX_ID_LEN } from '../http-util.js';
+import { MAX_ID_LEN } from '../util/http-util.js';
+import { DEFAULT_SEARCH_CANDIDATE_LIMIT } from '../store/rows.js';
+import { DEFAULT_CONFIG } from '../core/config.js';
 // ── Tool definitions ──
 // HTTP sets no budget cap; 25x the recall default leaves room for large-context clients while bounding one call's work.
 const MAX_BUDGET_TOKENS = 25 * DEFAULT_RECALL_BUDGET;
@@ -43,7 +45,7 @@ export const TOOLS = [
                 },
                 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.',
+                    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 ${DEFAULT_SEARCH_CANDIDATE_LIMIT}. Rejected as RecallContractError code=invalid_scorer_window if 0/negative/non-finite/non-numeric.`,
                 },
                 session_id: {
                     type: 'string',
@@ -138,7 +140,7 @@ export const TOOLS = [
     },
     {
         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.',
+        description: "Report whether recalled memories were useful. Good outcomes slow a memory's decay and bad ones speed it up, in proportion to its record. Call after completing work.",
         inputSchema: {
             type: 'object',
             properties: {
@@ -160,7 +162,7 @@ export const TOOLS = [
                     type: 'number',
                     minimum: 0,
                     maximum: MAX_BUDGET_TOKENS,
-                    description: `Max tokens (default: config.defaultContextBudget, 3000; max ${MAX_BUDGET_TOKENS})`,
+                    description: `Max tokens (default: config.defaultContextBudget, ${DEFAULT_CONFIG.defaultContextBudget}; max ${MAX_BUDGET_TOKENS})`,
                 },
                 scope: {
                     type: 'string',

package/dist/objects/customer-notes.d.ts

@@ -0,0 +1,44 @@
+/** customer_note object: many discrete notes per free-form `customer` column (no entities FK yet), each with its own supersede chain.
+ *  The `customer_notes` table is the source of truth; the memory mirror (memory_id NULLABLE, ON DELETE SET NULL) is for recall. */
+import type { KeysetPosition } from '../util/keyset.js';
+import type { SavableDescriptor } from './descriptor.js';
+import type { CustomerNote, NoteStatus } from '../store/object-types.js';
+export type { CustomerNote, NoteStatus } from '../store/object-types.js';
+export declare const VALID_NOTE_STATES: ReadonlySet<NoteStatus>;
+/** Field caps (untrusted at the HTTP/SDK boundary). note is a body, so a larger cap
+ *  than the 4096 short-field convention. */
+export declare const MAX_CUSTOMER_LEN = 256;
+export declare const MAX_NOTE_LEN = 8192;
+export declare const MAX_CHANGE_SUMMARY_LEN = 4096;
+export interface SaveCustomerNoteOpts {
+    customer: string;
+    note: string;
+    /** The delta note for a supersession; ignored (stored NULL) on a fresh create. */
+    changeSummary?: string;
+    /** Table id of an ACTIVE note this new version supersedes. */
+    supersedesNoteId?: number;
+    /** Extra memory tags merged after ['customer_note', 'customer:<lc>']. */
+    extraTags?: string[];
+}
+export interface ListCustomerNotesOpts {
+    status?: NoteStatus;
+    /** Filter to a single customer. */
+    customer?: string;
+    limit?: number;
+    /** Resume after this row: the position the previous page ended on. */
+    after?: KeysetPosition;
+}
+export declare const CUSTOMER_NOTE: SavableDescriptor<'customer_note', SaveCustomerNoteOpts>;
+/** Create a customer_note, or a new version superseding an existing one, in the `objects` store group's one transaction.
+ *  The mirror carries a `customer:<lc>` tag so scope-aware recall treats the note as entity-local. */
+export declare function saveCustomerNote(hippoRoot: string, tenantId: string, opts: SaveCustomerNoteOpts, actor?: string): CustomerNote;
+/** Close (retire) an active note; CAS on status='active', 0 changes means not-found or not-active. */
+export declare function closeCustomerNote(hippoRoot: string, tenantId: string, id: number, actor?: string): CustomerNote;
+export declare function loadCustomerNoteById(hippoRoot: string, tenantId: string, id: number): CustomerNote | null;
+export declare function loadCustomerNotes(hippoRoot: string, tenantId: string, opts?: ListCustomerNotesOpts): CustomerNote[];
+/** All ACTIVE notes for a customer, newest first. Returns a LIST, unlike project_brief's single-or-null
+ *  loadActiveBriefForRepo: a customer accrues many notes. */
+export declare function loadActiveNotesForCustomer(hippoRoot: string, tenantId: string, customer: string, opts?: {
+    limit?: number;
+}): CustomerNote[];
+//# sourceMappingURL=customer-notes.d.ts.map