hippo-memory 1.70.0 → 1.71.0

package/dist/learn/invalidation.d.ts

@@ -20,24 +20,11 @@ export interface InvalidationOptions {
     /** Consider ONLY this memory id (no content/tag matching). */
     onlyId?: string;
 }
-/**
- * Extract what was replaced/removed from a commit message.
- * Returns null if the commit isn't a breaking/migration change.
- */
+/** Extract what was replaced/removed from a commit message.
+ *  Returns null if the commit isn't a breaking/migration change. */
 export declare function extractInvalidationTarget(message: string): InvalidationTarget | null;
-/**
- * Find memories that reference the invalidated pattern and weaken them.
- * - Halves half_life_days
- * - Sets confidence to 'stale'
- * - Adds 'invalidated' tag
- * - Skips pinned memories (reported in skippedPinned)
- *
- * Tag matching is EXACT (2026-06-09 incident): the FULL pattern must equal a
- * tag. Token-level matching applies to content only, so a pattern that merely
- * CONTAINS a common tag word ("hippo") can no longer mass-weaken every memory
- * carrying that tag. Both callers (the CLI `invalidate` command and the
- * auto-learn-from-git path) inherit this contract.
- */
+/** Find memories that reference the invalidated pattern and weaken them (halve half_life_days, confidence 'stale', add 'invalidated' tag; pinned are skipped).
+ *  Tag matching is EXACT: the FULL pattern must equal a tag, so a pattern merely containing a common tag word cannot mass-weaken every memory with that tag. */
 export declare function invalidateMatching(hippoRoot: string, target: InvalidationTarget, tenantId?: string, options?: InvalidationOptions): InvalidationResult;
 /** invalidateMatching for a batch: matches against `live`, the caller's list of the tenant's rows, and keeps it current.
  *  Each match is read again before it is weakened, so a row another writer changed since the list was read is never written back stale. */
@@ -73,6 +60,7 @@ export interface ChurnStaleResult {
     preview: ChurnStalePreviewRow[];
     error?: string;
 }
-/** Flags memories whose named file/symbol/script changed or disappeared since storage (or last confirmation); only adds/removes CHURN_STALE_TAG, never confidence/half-life/strength. */
+/** Flags memories whose named file/symbol/script changed or disappeared since storage (or last
+ * confirmation); only adds/removes CHURN_STALE_TAG, never confidence/half-life/strength. */
 export declare function detectChurnStale(hippoRoot: string, repoRoot: string, opts: DetectChurnStaleOptions): ChurnStaleResult;
 //# sourceMappingURL=invalidation.d.ts.map

package/dist/learn/invalidation.js

@@ -4,10 +4,8 @@ import { chunked, loadAllEntries, loadEntriesByIds } from '../store/entry-reads.
 import { CHURN_STALE_TAG } from '../core/memory.js';
 import { GitReadError, gitLsFilesAtHead, fetchChurnWindowLog, gitGrepPresence, resolveCommitBefore, packageScriptsAt, } from './churn-git.js';
 const HEADLINE_CHARS = 60;
-/**
- * Extract what was replaced/removed from a commit message.
- * Returns null if the commit isn't a breaking/migration change.
- */
+/** Extract what was replaced/removed from a commit message.
+ *  Returns null if the commit isn't a breaking/migration change. */
 export function extractInvalidationTarget(message) {
     // Strip conventional commit prefix (e.g., "feat(scope): ")
     const body = message.replace(/^[a-z]+(\([^)]*\))?:\s*/i, '').trim();
@@ -44,25 +42,11 @@ export function extractInvalidationTarget(message) {
     }
     return null;
 }
-/**
- * Find memories that reference the invalidated pattern and weaken them.
- * - Halves half_life_days
- * - Sets confidence to 'stale'
- * - Adds 'invalidated' tag
- * - Skips pinned memories (reported in skippedPinned)
- *
- * Tag matching is EXACT (2026-06-09 incident): the FULL pattern must equal a
- * tag. Token-level matching applies to content only, so a pattern that merely
- * CONTAINS a common tag word ("hippo") can no longer mass-weaken every memory
- * carrying that tag. Both callers (the CLI `invalidate` command and the
- * auto-learn-from-git path) inherit this contract.
- */
+/** Find memories that reference the invalidated pattern and weaken them (halve half_life_days, confidence 'stale', add 'invalidated' tag; pinned are skipped).
+ *  Tag matching is EXACT: the FULL pattern must equal a tag, so a pattern merely containing a common tag word cannot mass-weaken every memory with that tag. */
 export function invalidateMatching(hippoRoot, target, tenantId, options) {
-    // L9: tenantId opt-in. When provided, only this tenant's memories are
-    // considered for weakening. When undefined, behaves as it did pre-1.12.1
-    // (host-wide invalidation across all tenants in the store).
-    // options.onlyId resolves by FILTERING this tenant-scoped list — never a
-    // direct id lookup — so an id from another tenant is invisible here.
+    // tenantId opt-in: when set, only that tenant's memories are weakened; undefined is host-wide.
+    // options.onlyId filters this tenant-scoped list rather than looking up an id directly, so another tenant's id is invisible here.
     const { result, weakened } = weakenMatches(loadAllEntries(hippoRoot, tenantId), target, options);
     writeEntriesSeparately(hippoRoot, weakened);
     return result;
@@ -381,7 +365,8 @@ function recordChurnEvidence(git, candidates, anchorOf, result) {
     }
     return toTag;
 }
-/** Flags memories whose named file/symbol/script changed or disappeared since storage (or last confirmation); only adds/removes CHURN_STALE_TAG, never confidence/half-life/strength. */
+/** Flags memories whose named file/symbol/script changed or disappeared since storage (or last
+ * confirmation); only adds/removes CHURN_STALE_TAG, never confidence/half-life/strength. */
 export function detectChurnStale(hippoRoot, repoRoot, opts) {
     const dryRun = opts.dryRun === true;
     if (!opts.projectName)
@@ -408,9 +393,7 @@ export function detectChurnStale(hippoRoot, repoRoot, opts) {
     const result = { checked: 0, marked: 0, alreadyMarked: 0, skippedPinned, dryRun, preview: [] };
     try {
         const git = loadChurnGitView(repoRoot, opts.legacyName ?? opts.projectName, candidates, anchorOf, needs);
-        // Collected here, written only after every candidate's evidence is
-        // computed: a GitReadError thrown mid-loop must never leave an earlier
-        // candidate tagged while a later one aborts the run untagged.
+        // Collected here and written only after every candidate's evidence is computed, so a GitReadError mid-loop cannot leave an earlier candidate tagged.
         const toTag = recordChurnEvidence(git, candidates, anchorOf, result);
         if (!dryRun && toTag.length > 0)
             tagChurnStale(hippoRoot, opts.tenantId, toTag, confirmedAt);

package/dist/mcp/admin-tools.js

@@ -2,7 +2,7 @@
 import { evalNow } from '../core/ablation.js';
 import { loadStrengthTallies } from '../store/candidates.js';
 import { countOpenConflicts, listTouchableConflicts, resolveConflict } from '../store/conflicts.js';
-import { shareMemory, listPeers } from '../sharing/shared.js';
+import { shareMemory, listPeers } from '../sharing/share.js';
 import { requireGroup, storeFor } from '../store/index.js';
 import { NotFoundError } from '../core/api-errors.js';
 import { classifyOriginProject } from '../core/project-identity.js';
@@ -106,10 +106,8 @@ export function runShareTool({ args, ctx, hippoRoot, tenantId }) {
     // Checked before shareMemory, whose personal-row refusal would tell another person the id exists.
     if (!canTouchScope(mcpActor(ctx), memoryScope(hippoRoot, shareId)))
         throw new NotFoundError(`Memory not found: ${shareId}`);
-    // 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.
+    // Pass tenantId so shareMemory's readEntry filters by tenant; otherwise a Bearer for tenant A could share tenant B's id to the global store.
+    // The 'Memory not found' error matches the cross-tenant deny shape elsewhere.
     const shared = shareMemory(hippoRoot, shareId, { force, tenantId });
     if (!shared)
         return 'Transfer score too low. Use force=true to override.';

package/dist/mcp/memory-tools.js

@@ -13,11 +13,8 @@ export async function runRememberTool({ args, ctx, hippoRoot, config, tenantId }
         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.
+    // Route through api/index.ts so audit_log captures the caller identity like CLI/REST: the auth-resolved ctx.actor under HTTP-MCP, 'mcp' for stdio.
+    // The entry is re-read to surface the half-life used in the MCP response.
     const apiCtx = {
         hippoRoot,
         tenantId,
@@ -44,10 +41,8 @@ export async function runOutcomeTool({ args, ctx, hippoRoot, tenantId }) {
     const ids = lastRecalledIds.get(clientKey) ?? [];
     if (ids.length === 0)
         return 'No recent recalls to apply outcome to.';
-    // Route through src/api/index.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.
+    // Route through src/api/index.ts so audit_log captures the caller identity (auth-resolved ctx.actor under HTTP-MCP, 'mcp' for stdio) and tenant scoping is
+    // uniform; outcome() also skips cross-tenant ids silently.
     const apiCtx = {
         hippoRoot,
         tenantId,

package/dist/mcp/protocol.d.ts

@@ -27,25 +27,14 @@ interface McpResponse {
 /** JSON-RPC reply for a request that threw: typed API errors keep their text; anything else is logged and answered generically. */
 export declare function mcpErrorResponse<E>(id: McpResponse['id'], err: E, requestId?: string): McpResponse;
 export type { McpRequest, McpResponse };
-/**
- * Optional execution context threaded from a non-stdio transport. When the
- * HTTP transport in src/server.ts calls handleMcpRequest, it knows the
- * server's bound hippoRoot and the auth-resolved tenantId/actor. Passing
- * those through here lets executeTool skip the findHippoRoot() walk and
- * the env-based resolveTenantId({}) fallback — both of which would
- * otherwise produce the wrong store and the wrong tenant for HTTP callers.
- *
- * Stdio callers pass nothing; behavior stays unchanged for that path.
- */
+/** Optional context from a non-stdio transport (the HTTP server's bound hippoRoot and auth-resolved tenantId/actor), so executeTool skips the
+ * findHippoRoot() walk and the env-based resolveTenantId({}) fallback, which would pick the wrong store and tenant for HTTP callers. Stdio passes nothing. */
 export interface McpContext {
     hippoRoot: string;
     tenantId: string;
     actor: string;
-    /**
-     * The caller's role from the HTTP transport's auth. Absent for stdio, which
-     * is the local operator and runs as admin. Tools must use this rather than
-     * assuming admin, or a member key over HTTP-MCP would act as admin.
-     */
+    /** The caller's role from the HTTP transport's auth; absent for stdio (the local operator, admin). Tools must use this, or a member key over HTTP-MCP
+     * would act as admin. */
     role?: 'admin' | 'member';
     /** Scope grants for the HTTP-MCP caller's key. Absent for stdio (admin, needs none). */
     scopes?: readonly string[];
@@ -56,19 +45,12 @@ export interface McpContext {
     project?: CallerProject;
     store?: HippoStore;
     autoSleep?: false;
-    /**
-     * Per-client key for state isolation under HTTP-MCP. For stdio: 'stdio-${pid}'
-     * (one process = one client). For HTTP-SSE / HTTP MCP: hash(bearer + remoteAddr)
-     * built by src/server.ts when constructing McpContext for the request.
-     * Optional for backwards compatibility; defaults to `${tenantId}:default`.
-     */
+    /** Per-client key for state isolation under HTTP-MCP: 'stdio-${pid}' for stdio, hash(bearer + remoteAddr) for HTTP (built in src/server/mcp-http.ts);
+     * defaults to `${tenantId}:default`. */
     clientKey?: string;
 }
-/**
- * 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.
- */
+/** The api-layer actor for a tool call: stdio (no ctx) is the local operator and runs as admin; over HTTP the authenticated role is used, so a member key
+ * never acts as admin. */
 export declare function mcpActor(ctx: McpContext | undefined): ApiActor;
 /** One tool call after the store, config and tenant are resolved; every handler reads the same four. */
 export interface ToolCall {

package/dist/mcp/protocol.js

@@ -4,7 +4,7 @@ import { randomUUID } from 'node:crypto';
 import { INTERNAL_ERROR_MESSAGE, mapApiError } from '../util/http-util.js';
 import { errorFields, errorMessage, log } from '../util/log.js';
 import { currentRequestId } from '../util/request-scope.js';
-import { getGlobalRoot } from '../sharing/shared.js';
+import { getGlobalRoot } from '../sharing/global-store.js';
 import { findHippoStoreDir } from '../core/project-identity.js';
 import { isStoreBusy, STORE_BUSY_MESSAGE } from '../db/index.js';
 // ── Find hippo root ──
@@ -31,11 +31,8 @@ export function mcpErrorResponse(id, err, requestId = currentRequestId() ?? rand
         error: { code: -32603, message: `${INTERNAL_ERROR_MESSAGE} (request id ${requestId})`, data: { requestId } },
     };
 }
-/**
- * The api-layer actor for a tool call. 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.
- */
+/** The api-layer actor for a tool call: stdio (no ctx) is the local operator and runs as admin; over HTTP the authenticated role is used, so a member key
+ * never acts as admin. */
 export function mcpActor(ctx) {
     const actor = { subject: ctx?.actor ?? 'mcp', role: ctx?.role ?? 'admin', scopes: ctx?.scopes };
     if (ctx?.viaAuthResolver)

package/dist/mcp/recall-tools.js

@@ -2,7 +2,7 @@
 import * as path from 'path';
 import { fitBudget } from '../search/finalize.js';
 import { dropHeldCopies, duplicateKey, storedTextKeys } from '../util/same-text.js';
-import { retrieve as apiRetrieve, drillDown as apiDrillDown, assemble as apiAssemble, getContext as apiGetContext, buildSuppressionSummary } from '../api/index.js';
+import { retrieve as apiRetrieve, drillDown as apiDrillDown, assemble as apiAssemble, getContext as apiGetContext } from '../api/index.js';
 import { autoDetectContext } from '../api/context-auto.js';
 import { resolveProjectIdentity } from '../core/project-identity.js';
 import { isSharedStore } from '../core/config.js';
@@ -85,14 +85,14 @@ function recallPresenter(budget, options) {
             const tail = showTail
                 ? dropHeldCopies(tailRows.filter((r) => !shownIds.has(r.id) && !shownKeys.has(duplicateKey(r.content))), (r) => r)
                 : [];
-            const s = buildSuppressionSummary({
+            const s = {
                 totalCandidates: pool.length + droppedByScope,
                 droppedPreRank: droppedByScope + cut.length - list.length, // the bucket CLI and API recall put hidden copies in
                 droppedByBudget: Math.max(0, pool.length - cut.length), // an upper bound: rows that never matched count too
                 summarySubstitutionsAdded: tail.filter((r) => r.isSummary).length,
                 freshTailAdded: tail.filter((r) => r.isFreshTail && !r.isSummary).length,
                 suppressedByInterference: anchoring?.reason === 'memory_dominance' ? 1 : 0,
-            });
+            };
             // Anchoring is the stronger pull, so it prints first; the Cutoff block sits above the list, where the agent reads it.
             let text = biasHintSections(anchoring, availability);
             if (showPlan)

package/dist/mcp/request.d.ts

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

package/dist/mcp/request.js

@@ -1,7 +1,7 @@
 // Transport-agnostic request handling: tool dispatch table, tool execution and the JSON-RPC method switch.
 import { errorMessage, log } from '../util/log.js';
 import { STORE_NOT_PORTED_MESSAGE } from '../util/http-util.js';
-import { getGlobalRoot, initGlobal } from '../sharing/shared.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';
@@ -17,12 +17,8 @@ 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, isJsonObject } from '../util/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.
- */
+/** 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)
@@ -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.
@@ -155,13 +144,8 @@ async function callTool(id, params, ctx) {
         },
     };
 }
-/**
- * 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.
- */
+/** 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) {

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

package/dist/mcp/session-state.js

@@ -1,18 +1,12 @@
 // Per-process state the MCP tools share across calls: recall rings, last recalled ids, auto-sleep runs.
+import { DEFAULT_TENANT_ID } from '../util/env.js';
 import { resetSessionRings } from '../api/recall-record.js';
 /** 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.
+// 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 {
@@ -28,7 +22,7 @@ class RecentRecalls extends Map {
 export const lastRecalledIds = new RecentRecalls();
 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/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,12 +1,13 @@
 // Stdio transport: newline-delimited JSON-RPC frames in on stdin, replies out on stdout.
 import { exitAfterFlush, installCrashHandlers } from '../util/crash-handlers.js';
-import { errorMessage, log } from '../util/log.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
+import { requestDeadlineMs } from '../server/deadline.js';
 import { parseFrame } from './framing.js';
 import { mcpErrorResponse } from './protocol.js';
 import { handleMcpRequest } from './request.js';
 import { isJsonNumber, isJsonString, isJsonObject } from '../util/json.js';
 import { randomUUID } from 'node:crypto';
-import { runWithRequestId } from '../util/request-scope.js';
+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) {
@@ -61,6 +62,39 @@ async function exitWhenDrained() {
     }
     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;
     try {
@@ -77,22 +111,24 @@ function dispatch(body) {
     }
     const req = parsed;
     if (req.method.startsWith('notifications/')) {
+        const stopWatching = watchDeadline(req, false);
         track(req.method, handleMcpRequest(req).then(() => { }).catch((err) => {
-            log.error(`mcp notification ${req.method} failed: ${errorMessage(err)}`);
-        }));
+            log.error(`mcp notification ${req.method} failed: ${errorMessage(err)}`, errorFields(err));
+        }).finally(stopWatching));
         return;
     }
-    track(req.method, 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, withoutRefused(chunk)]);

package/dist/mcp/tools.js

@@ -2,6 +2,8 @@
 import { DEFAULT_RECALL_BUDGET } from '../core/search-types.js';
 import { DEFAULT_ASSEMBLE_BUDGET } from '../api/assemble.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',