hippo-memory 1.57.0 → 1.59.0

package/dist/importers.js

@@ -13,6 +13,7 @@ import { remember, archiveRaw, isPrivateScope } from './api.js';
 import { openHippoDb, closeHippoDb } from './db.js';
 import { RejectedValueError, checkRejectionGuard } from './rejection.js';
 import { loadConfig } from './config.js';
+import { vetSecrets } from './secret-detect.js';
 // ---------------------------------------------------------------------------
 // Shared core: dedup + write
 // ---------------------------------------------------------------------------
@@ -33,6 +34,7 @@ export function importEntries(chunks, source, tags, options) {
     let imported = 0;
     let skipped = 0;
     let rejected = 0;
+    let redacted = 0;
     const entries = [];
     // AT1 P2 fix: a dry-run preview never called writeEntry, so it never
     // checked tombstones either — every non-duplicate chunk counted as
@@ -42,7 +44,9 @@ export function importEntries(chunks, source, tags, options) {
     const dryRunDb = options.dryRun ? openHippoDb(targetRoot) : null;
     try {
         for (const raw of chunks) {
-            const trimmed = raw.trim();
+            const original = raw.trim();
+            const trimmed = vetSecrets(original, allTags, true).content;
+            const wasRedacted = trimmed !== original;
             if (trimmed.length > 1000) {
                 console.error(`Warning: imported memory truncated from ${trimmed.length} to 1000 chars`);
             }
@@ -109,8 +113,10 @@ export function importEntries(chunks, source, tags, options) {
             }
             entries.push(entry);
             imported++;
+            if (wasRedacted)
+                redacted++;
         }
-        return { total, imported, skipped, rejected, entries };
+        return { total, imported, skipped, rejected, redacted, entries };
     }
     finally {
         if (dryRunDb)
@@ -430,6 +436,7 @@ export function importMarkdown(filePath, options) {
             // AT1 P2 fix: `rejected` is now optional on ImportResult (compat) — tolerate
             // undefined on either side of the accumulation.
             rejected: (totalResult.rejected ?? 0) + (result.rejected ?? 0),
+            redacted: (totalResult.redacted ?? 0) + (result.redacted ?? 0),
             entries: [...totalResult.entries, ...result.entries],
         };
     }
@@ -695,6 +702,7 @@ export function importVault(folderPath, options) {
     let skipped = 0;
     let rejected = 0;
     let archived = 0;
+    let redacted = 0;
     const entries = [];
     const baseHalfLifeDays = loadConfig(hippoRoot).defaultHalfLifeDays;
     // AT1 P2 fix: dry-run never called remember(), so it never probed
@@ -796,7 +804,8 @@ export function importVault(folderPath, options) {
             // remember() owns the actual write. We build an `echo` of the SAME content +
             // tags via createMemory purely for the ImportResult, then reconcile its id to
             // remember()'s real row id so entries[] reflects the row that landed.
-            const echo = createMemory(body, {
+            const content = vetSecrets(body, tags, true).content;
+            const echo = createMemory(content, {
                 kind: 'raw',
                 tags,
                 scope,
@@ -815,7 +824,7 @@ export function importVault(folderPath, options) {
                 // loud each time via the rejected count.
                 try {
                     const result = remember(ctx, {
-                        content: body,
+                        content,
                         kind: 'raw',
                         artifactRef,
                         owner: 'agent:vault-import',
@@ -848,6 +857,8 @@ export function importVault(folderPath, options) {
             }
             entries.push(echo);
             imported++;
+            if (content !== body)
+                redacted++;
         }
     }
     finally {
@@ -867,7 +878,7 @@ export function importVault(folderPath, options) {
                 archiveRaw(ctx, row.id, `source_deleted:${artifactRef}`);
         }
     }
-    return { total, imported, skipped, rejected, archived, entries };
+    return { total, imported, skipped, rejected, archived, redacted, entries };
 }
 /** Local tolerant JSON-array parse for the loader's `tags_json` column. The
  *  store's own `parseJsonArray` is not exported; this matches its contract

package/dist/incidents.js

@@ -25,6 +25,7 @@
  * the row, default `[]`. On save, every id must exist in the SAME tenant; a
  * cross-tenant or nonexistent id is rejected (throw) before the insert.
  */
+import { BadRequestError, ConflictError, NotFoundError } from './api-errors.js';
 import { openHippoDb, closeHippoDb } from './db.js';
 import { writeEntry } from './store.js';
 import { assertTenantId } from './tenant.js';
@@ -89,7 +90,7 @@ const INCIDENT_COLS = `
 export function saveIncident(hippoRoot, tenantId, opts, actor = 'cli') {
     assertTenantId('saveIncident', tenantId);
     if (!opts.incidentText)
-        throw new Error('saveIncident: incidentText is required');
+        throw new BadRequestError('saveIncident: incidentText is required');
     const now = new Date().toISOString();
     const content = opts.context
         ? `${opts.incidentText}\n\nContext: ${opts.context}`
@@ -118,7 +119,7 @@ export function saveIncident(hippoRoot, tenantId, opts, actor = 'cli') {
                 // SAFETY: row shape matches the single `id` column named in the SELECT above.
                 const exists = db.prepare(`SELECT id FROM memories WHERE id = ? AND tenant_id = ?`).get(linkId, tenantId);
                 if (!exists) {
-                    throw new Error(`saveIncident: linked memory ${linkId} not found for tenant ${tenantId}`);
+                    throw new NotFoundError(`saveIncident: linked memory ${linkId} not found for tenant ${tenantId}`);
                 }
                 validated.push(linkId);
             }
@@ -164,7 +165,7 @@ export function saveIncident(hippoRoot, tenantId, opts, actor = 'cli') {
 export function resolveIncident(hippoRoot, tenantId, id, resolutionText, actor = 'cli') {
     assertTenantId('resolveIncident', tenantId);
     if (!resolutionText || !resolutionText.trim()) {
-        throw new Error('resolveIncident: resolutionText is required (non-empty)');
+        throw new BadRequestError('resolveIncident: resolutionText is required (non-empty)');
     }
     const now = new Date().toISOString();
     const db = openHippoDb(hippoRoot);
@@ -180,15 +181,15 @@ export function resolveIncident(hippoRoot, tenantId, id, resolutionText, actor =
                 // SAFETY: row shape matches the single `status` column named in the SELECT above.
                 const existing = db.prepare(`SELECT status FROM incidents WHERE id = ? AND tenant_id = ?`).get(id, tenantId);
                 if (!existing) {
-                    throw new Error(`resolveIncident: incident ${id} not found for tenant ${tenantId}`);
+                    throw new NotFoundError(`resolveIncident: incident ${id} not found for tenant ${tenantId}`);
                 }
-                throw new Error(`resolveIncident: incident ${id} is not open (status='${existing.status}'); only open incidents can be resolved.`);
+                throw new ConflictError(`resolveIncident: incident ${id} is not open (status='${existing.status}'); only open incidents can be resolved.`);
             }
             // SAFETY: row's shape matches the columns named in INCIDENT_COLS above.
             const row = db.prepare(`SELECT ${INCIDENT_COLS} FROM incidents WHERE id = ? AND tenant_id = ?`)
                 .get(id, tenantId);
             if (!row)
-                throw new Error(`resolveIncident: incident ${id} not found after UPDATE`);
+                throw new NotFoundError(`resolveIncident: incident ${id} not found after UPDATE`);
             appendAuditEvent(db, {
                 tenantId,
                 actor,
@@ -235,15 +236,15 @@ export function closeIncident(hippoRoot, tenantId, id, actor = 'cli') {
                 // SAFETY: row shape matches the single `status` column named in the SELECT above.
                 const existing = db.prepare(`SELECT status FROM incidents WHERE id = ? AND tenant_id = ?`).get(id, tenantId);
                 if (!existing) {
-                    throw new Error(`closeIncident: incident ${id} not found for tenant ${tenantId}`);
+                    throw new NotFoundError(`closeIncident: incident ${id} not found for tenant ${tenantId}`);
                 }
-                throw new Error(`closeIncident: incident ${id} is already closed (status='${existing.status}'); only open or resolved incidents can be closed.`);
+                throw new ConflictError(`closeIncident: incident ${id} is already closed (status='${existing.status}'); only open or resolved incidents can be closed.`);
             }
             // SAFETY: row's shape matches the columns named in INCIDENT_COLS above.
             const row = db.prepare(`SELECT ${INCIDENT_COLS} FROM incidents WHERE id = ? AND tenant_id = ?`)
                 .get(id, tenantId);
             if (!row)
-                throw new Error(`closeIncident: incident ${id} not found after UPDATE`);
+                throw new NotFoundError(`closeIncident: incident ${id} not found after UPDATE`);
             appendAuditEvent(db, {
                 tenantId,
                 actor,
@@ -289,7 +290,7 @@ export function loadIncidents(hippoRoot, tenantId, opts = {}) {
         let rows;
         if (opts.status) {
             if (!VALID_INCIDENT_STATES.has(opts.status)) {
-                throw new Error(`loadIncidents: status must be one of ${Array.from(VALID_INCIDENT_STATES).join('|')}; got ${opts.status}`);
+                throw new BadRequestError(`loadIncidents: status must be one of ${Array.from(VALID_INCIDENT_STATES).join('|')}; got ${opts.status}`);
             }
             // SAFETY: rows' shape matches the columns named in INCIDENT_COLS above.
             rows = db.prepare(`

package/dist/judgment.js

@@ -1,10 +1,10 @@
 /** Typed judgment over capture candidates via TypeSafe's Jev (System One).
  *  Regex picks WHAT is a candidate; it cannot say what is worth keeping, so
  *  every captured memory currently lands on a flat schema_fit of 0.5. */
+import { fetchWithRetry } from './http-retry.js';
 const ENDPOINT = 'https://api.typesafe.ai/v1/systemone';
 const DEFAULT_MODEL = 'jev-1.13.0';
 const MAX_CONCURRENCY = 8;
-const RETRY_STATUS = new Set([429, 529]);
 const QUESTIONS = {
     durable: {
         type: 'noul',
@@ -48,11 +48,12 @@ function toConfidenceTier(kindConfidence) {
         return 'observed';
     return 'inferred';
 }
-async function postOnce(content, opts) {
-    const fetchFn = opts.fetcher ?? fetch;
+/** Capture-time judging must not hold a write for long: one budget per attempt, shorter than the LLM calls. */
+const JUDGE_TIMEOUT_MS = 15_000;
+async function post(content, opts) {
     let res;
     try {
-        res = await fetchFn(ENDPOINT, {
+        res = await fetchWithRetry(ENDPOINT, {
             method: 'POST',
             headers: {
                 'content-type': 'application/json',
@@ -63,16 +64,12 @@ async function postOnce(content, opts) {
                 model: opts.model ?? DEFAULT_MODEL,
                 questions: QUESTIONS,
             }),
-        });
+        }, { timeoutMs: JUDGE_TIMEOUT_MS, fetchFn: opts.fetcher });
     }
     catch {
         return null;
     }
-    if (RETRY_STATUS.has(res.status))
-        return { retryable: true };
-    if (!res.ok)
-        return null;
-    return { res };
+    return res.ok ? res : null;
 }
 /** `null` on any failure, so a Jev outage degrades capture to today's
  *  behaviour instead of blocking the write. */
@@ -80,19 +77,15 @@ export async function judge(content, opts) {
     const trimmed = content.trim();
     if (trimmed.length < 3)
         return null;
-    let attempt = await postOnce(trimmed, opts);
-    if (attempt && 'retryable' in attempt) {
-        await new Promise((resolve) => setTimeout(resolve, 500));
-        attempt = await postOnce(trimmed, opts);
-    }
-    if (!attempt || 'retryable' in attempt)
+    const res = await post(trimmed, opts);
+    if (!res)
         return null;
     let data;
     try {
         // SAFETY: the documented Jev response is `{ answers: { <name>: Answer } }`
         // keyed by the question names posted above; every field read below is
         // optional-chained and range-checked before use, so a lie here returns null.
-        data = await attempt.res.json();
+        data = await res.json();
     }
     catch {
         return null;

package/dist/log.d.ts

@@ -0,0 +1,25 @@
+/** Leveled stderr logger. `HIPPO_LOG` picks the threshold (error, warn, info, debug); unset or unknown means warn. */
+export type LogLevel = 'error' | 'warn' | 'info' | 'debug';
+/** Extra key=value pairs appended to the line; `requestId` ties a line to one HTTP request. */
+export interface LogFields {
+    requestId?: string;
+    [key: string]: string | number | boolean | undefined;
+}
+/** The active threshold, read on every call so a test or a long-lived server can change it without a restart. */
+export declare function logThreshold(): LogLevel;
+export declare function isLevelEnabled(level: LogLevel): boolean;
+/** Same `[hippo] ` prefix the existing stderr lines use, so default-level output reads as before. */
+export declare function formatLogLine(level: LogLevel, message: string, fields?: LogFields): string;
+/** Write `message` at `level` the first time `key` is seen in this process; later calls are dropped. */
+declare function once(key: string, level: LogLevel, message: string, fields?: LogFields): void;
+export declare const log: {
+    readonly error: (message: string, fields?: LogFields) => void;
+    readonly warn: (message: string, fields?: LogFields) => void;
+    readonly info: (message: string, fields?: LogFields) => void;
+    readonly debug: (message: string, fields?: LogFields) => void;
+    readonly once: typeof once;
+};
+/** Test hook: forget which once-keys have fired. */
+export declare function resetLogOnce(): void;
+export {};
+//# sourceMappingURL=log.d.ts.map

package/dist/log.js

@@ -0,0 +1,48 @@
+/** Leveled stderr logger. `HIPPO_LOG` picks the threshold (error, warn, info, debug); unset or unknown means warn. */
+const RANK = { error: 0, warn: 1, info: 2, debug: 3 };
+function isLogLevel(value) {
+    return Object.hasOwn(RANK, value);
+}
+/** The active threshold, read on every call so a test or a long-lived server can change it without a restart. */
+export function logThreshold() {
+    const raw = process.env.HIPPO_LOG?.trim().toLowerCase() ?? '';
+    return isLogLevel(raw) ? raw : 'warn';
+}
+export function isLevelEnabled(level) {
+    return RANK[level] <= RANK[logThreshold()];
+}
+// A field value is caller data; flattening newlines keeps one event on one line.
+const oneLine = (value) => value.replace(/[\r\n]+/g, ' ');
+/** Same `[hippo] ` prefix the existing stderr lines use, so default-level output reads as before. */
+export function formatLogLine(level, message, fields = {}) {
+    const extras = Object.entries(fields)
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => ` ${k}=${oneLine(String(v))}`)
+        .join('');
+    return `[hippo] ${level}: ${oneLine(message)}${extras}`;
+}
+function write(level, message, fields) {
+    if (!isLevelEnabled(level))
+        return;
+    process.stderr.write(`${formatLogLine(level, message, fields)}\n`);
+}
+const onceKeys = new Set();
+/** Write `message` at `level` the first time `key` is seen in this process; later calls are dropped. */
+function once(key, level, message, fields) {
+    if (onceKeys.has(key))
+        return;
+    onceKeys.add(key);
+    write(level, message, fields);
+}
+export const log = {
+    error: (message, fields) => write('error', message, fields),
+    warn: (message, fields) => write('warn', message, fields),
+    info: (message, fields) => write('info', message, fields),
+    debug: (message, fields) => write('debug', message, fields),
+    once,
+};
+/** Test hook: forget which once-keys have fired. */
+export function resetLogOnce() {
+    onceKeys.clear();
+}
+//# sourceMappingURL=log.js.map

package/dist/mcp/server.js

@@ -39,6 +39,7 @@ export function __resetSessionRecallHistoryMcp() {
 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) {
@@ -205,6 +206,10 @@ function planningSection(r) {
     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',
@@ -213,7 +218,12 @@ const TOOLS = [
             type: 'object',
             properties: {
                 query: { type: 'string', description: 'What to search for in memory (natural language)' },
-                budget: { type: 'number', description: 'Max tokens to return (default: config.defaultBudget, 4000)' },
+                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.',
@@ -259,7 +269,9 @@ const TOOLS = [
                 },
                 budget: {
                     type: 'number',
-                    description: 'Token budget for the assembled context (default 4000). Eviction kicks in over budget.',
+                    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',
@@ -289,11 +301,15 @@ const TOOLS = [
                 },
                 limit: {
                     type: 'number',
-                    description: 'Max children to return (default 50).',
+                    minimum: 0,
+                    maximum: MAX_LIST_LIMIT,
+                    description: `Max children to return (default 50; max ${MAX_LIST_LIMIT}).`,
                 },
                 budget: {
                     type: 'number',
-                    description: 'Max total token cost (~ chars/4) of returned children. Truncates chronologically.',
+                    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',
@@ -342,7 +358,12 @@ const TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
-                budget: { type: 'number', minimum: 0, description: 'Max tokens (default: config.defaultContextBudget, 3000)' },
+                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.',
@@ -426,6 +447,9 @@ const TOOLS = [
         },
     },
 ];
+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
@@ -522,12 +546,7 @@ async function executeTool(name, args, ctx) {
             const summarizeOverflow = isJsonBoolean(args.summarize_overflow)
                 ? args.summarize_overflow
                 : undefined;
-            // v1.7.2 T4 — scorer_window: Number-coerce so non-numeric input
-            // (string 'abc', boolean, etc.) reaches api.retrieve() and produces
-            // the same typed RecallContractError(code='invalid_scorer_window')
-            // as HTTP. Codex CRITICAL[2]: do NOT use `typeof === 'number'` — that
-            // would silently default-200 on string `"5"` while HTTP 400s on the
-            // same value. Both transports must agree.
+            // 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);
@@ -760,17 +779,8 @@ async function executeTool(name, args, ctx) {
                 return 'No summary_id provided.';
             const limit = Number(args.limit);
             const budget = Number(args.budget);
-            // v0.30 / E5: depth walks N levels (default 1, hard cap 10).
-            // independent-review MED #5 fold: reject out-of-range explicitly
-            // (no silent clamp) so MCP callers see the constraint at their layer.
-            let depth;
-            if (args.depth !== undefined) {
-                const depthRaw = Number(args.depth);
-                if (!Number.isInteger(depthRaw) || depthRaw < 1 || depthRaw > 10) {
-                    return `depth must be an integer between 1 and 10 (got ${args.depth})`;
-                }
-                depth = depthRaw;
-            }
+            // 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,
@@ -862,7 +872,8 @@ async function executeTool(name, args, ctx) {
             }
             const halfLife = entry?.half_life_days ?? config.defaultHalfLifeDays;
             const tagStr = entry?.tags.join(', ') || tags.join(', ') || 'none';
-            return `Remembered [${result.id}] (half-life: ${halfLife}d, tags: ${tagStr})`;
+            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);
@@ -1043,7 +1054,8 @@ async function executeTool(name, args, ctx) {
             return peers.map((p) => `${p.project}: ${p.count} memories (latest: ${p.latest.slice(0, 10)})`).join('\n');
         }
         default:
-            return `Unknown tool: ${name}`;
+            // 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 ──
@@ -1074,8 +1086,24 @@ export async function handleMcpRequest(req, ctx) {
         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 {

package/dist/mcp/tool-args.d.ts

@@ -0,0 +1,21 @@
+export type ToolArgValue = string | number | boolean | null | ToolArgValue[] | {
+    [key: string]: ToolArgValue;
+};
+/** One property of a tool's inputSchema. Keywords outside this subset are not supported. */
+export interface ToolPropertySchema {
+    readonly type: 'string' | 'number' | 'integer' | 'boolean';
+    readonly description?: string;
+    readonly enum?: readonly (string | number | boolean)[];
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly maxLength?: number;
+}
+/** A tool's inputSchema: an object with named properties and an optional required list. */
+export interface ToolInputSchema {
+    readonly type: 'object';
+    readonly properties: Readonly<Record<string, ToolPropertySchema>>;
+    readonly required?: readonly string[];
+}
+/** One message per violation; undeclared properties pass, and `checkedDownstream` names keep the API layer's own error contract. */
+export declare function validateToolArgs(schema: ToolInputSchema, args: Readonly<Record<string, ToolArgValue>>, checkedDownstream?: ReadonlySet<string>): string[];
+//# sourceMappingURL=tool-args.d.ts.map

package/dist/mcp/tool-args.js

@@ -0,0 +1,80 @@
+// Hand-written for the JSON Schema subset the hippo tool definitions use, so the MCP server needs no validator dependency.
+function isArgString(v) {
+    return typeof v === 'string';
+}
+function isArgBoolean(v) {
+    return typeof v === 'boolean';
+}
+function isArgNumber(v) {
+    return typeof v === 'number' && Number.isFinite(v);
+}
+const NUMERIC_STRING = /^-?\d+(\.\d+)?$/;
+// LLM clients often send numbers as strings, and the handlers Number-coerce, so "4000" counts as 4000 while "12abc" does not.
+function asNumber(v) {
+    if (isArgNumber(v))
+        return v;
+    if (isArgString(v) && NUMERIC_STRING.test(v.trim()))
+        return Number(v.trim());
+    return null;
+}
+function describeValue(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    if (isArgString(v))
+        return JSON.stringify(v.length > 40 ? `${v.slice(0, 40)}...` : v);
+    if (isArgNumber(v) || isArgBoolean(v))
+        return String(v);
+    return 'object';
+}
+function checkProperty(name, schema, raw) {
+    const got = ` (got ${describeValue(raw)})`;
+    const isNumeric = schema.type === 'number' || schema.type === 'integer';
+    const value = isNumeric ? asNumber(raw) : raw;
+    switch (schema.type) {
+        case 'string':
+            if (!isArgString(value))
+                return `${name} must be a string${got}`;
+            if (schema.maxLength !== undefined && value.length > schema.maxLength) {
+                return `${name} must be at most ${schema.maxLength} characters (got ${value.length})`;
+            }
+            break;
+        case 'boolean':
+            if (!isArgBoolean(value))
+                return `${name} must be a boolean${got}`;
+            break;
+        case 'number':
+        case 'integer':
+            if (value === null || !isArgNumber(value))
+                return `${name} must be a number${got}`;
+            if (schema.type === 'integer' && !Number.isInteger(value))
+                return `${name} must be an integer${got}`;
+            if (schema.minimum !== undefined && value < schema.minimum)
+                return `${name} must be >= ${schema.minimum}${got}`;
+            if (schema.maximum !== undefined && value > schema.maximum)
+                return `${name} must be <= ${schema.maximum}${got}`;
+            break;
+    }
+    if (schema.enum !== undefined && !schema.enum.some((allowed) => allowed === value)) {
+        return `${name} must be one of ${schema.enum.map((e) => JSON.stringify(e)).join(', ')}${got}`;
+    }
+    return null;
+}
+/** One message per violation; undeclared properties pass, and `checkedDownstream` names keep the API layer's own error contract. */
+export function validateToolArgs(schema, args, checkedDownstream = new Set()) {
+    const problems = [];
+    for (const name of schema.required ?? []) {
+        if (!Object.hasOwn(args, name))
+            problems.push(`${name} is required`);
+    }
+    for (const [name, propSchema] of Object.entries(schema.properties)) {
+        if (!Object.hasOwn(args, name) || checkedDownstream.has(name))
+            continue;
+        const problem = checkProperty(name, propSchema, args[name]);
+        if (problem !== null)
+            problems.push(problem);
+    }
+    return problems;
+}
+//# sourceMappingURL=tool-args.js.map

package/dist/memory.js

@@ -2,6 +2,7 @@
  * Core data model for Hippo memory entries.
  * Based on the strength formula from PLAN.md.
  */
+import { BadRequestError } from './api-errors.js';
 import { randomUUID } from 'crypto';
 import { isDecayAblated, isOutcomeSlowAblated, isRecallBoostAblated, evalNow, } from './ablation.js';
 import { AGENT_MEMORY_TOOLS, toolSourcePrefix } from './agent-memories/tools.js';
@@ -332,11 +333,11 @@ export function canAutoDelete(entry) {
 export function createMemory(content, options = {}) {
     const trimmed = content.trim();
     if (trimmed.length < 3) {
-        throw new Error(`Memory content too short (${trimmed.length} chars, minimum 3): "${trimmed}"`);
+        throw new BadRequestError(`Memory content too short (${trimmed.length} chars, minimum 3): "${trimmed}"`);
     }
     const validOutcomes = ['success', 'failure', 'partial', null];
     if (options.trace_outcome !== undefined && !validOutcomes.includes(options.trace_outcome)) {
-        throw new Error(`Invalid trace_outcome: ${options.trace_outcome}. Must be 'success', 'failure', 'partial', or null.`);
+        throw new BadRequestError(`Invalid trace_outcome: ${options.trace_outcome}. Must be 'success', 'failure', 'partial', or null.`);
     }
     const now = evalNow().toISOString(); // honors HIPPO_FAKE_NOW (eval-only)
     const layer = options.layer ?? Layer.Episodic;

package/dist/overlap-index.d.ts

@@ -0,0 +1,7 @@
+/** Smallest number of shared tokens any qualifying pair can have, given either side's token count. */
+export type MinShared = (size: number) => number;
+/** Shared >= threshold * union >= threshold * size; one token of slack covers float rounding in the caller's Jaccard check. */
+export declare function jaccardMinShared(threshold: number, atLeast?: number): MinShared;
+/** Maps i to each j > i, ascending, that may share `minShared` tokens with set i; a superset the caller checks exactly, never a pair sharing no token. */
+export declare function overlapPartners(sets: readonly ReadonlySet<string>[], minShared: MinShared): (i: number) => number[];
+//# sourceMappingURL=overlap-index.d.ts.map

package/dist/overlap-index.js

@@ -0,0 +1,38 @@
+// All-pairs overlap join through an inverted index over rare-first token prefixes (prefix filtering, Chaudhuri et al. 2006).
+/** Shared >= threshold * union >= threshold * size; one token of slack covers float rounding in the caller's Jaccard check. */
+export function jaccardMinShared(threshold, atLeast = 1) {
+    return (size) => Math.max(atLeast, Math.ceil(threshold * size) - 1);
+}
+/** Maps i to each j > i, ascending, that may share `minShared` tokens with set i; a superset the caller checks exactly, never a pair sharing no token. */
+export function overlapPartners(sets, minShared) {
+    const docFreq = new Map();
+    for (const set of sets)
+        for (const t of set)
+            docFreq.set(t, (docFreq.get(t) ?? 0) + 1);
+    const rareFirst = (a, b) => ((docFreq.get(a) ?? 0) - (docFreq.get(b) ?? 0)) || (a < b ? -1 : a > b ? 1 : 0);
+    // Under one total order the first token two sets share lies in both sets' first size - minShared + 1 tokens.
+    const prefixes = sets.map((set) => {
+        const keep = set.size - Math.max(1, minShared(set.size)) + 1;
+        return keep > 0 ? [...set].sort(rareFirst).slice(0, keep) : [];
+    });
+    const postings = new Map();
+    prefixes.forEach((prefix, i) => {
+        for (const t of prefix) {
+            const list = postings.get(t);
+            if (list)
+                list.push(i);
+            else
+                postings.set(t, [i]);
+        }
+    });
+    return (i) => {
+        const found = new Set();
+        for (const t of prefixes[i]) {
+            const list = postings.get(t) ?? [];
+            for (let k = list.length - 1; k >= 0 && list[k] > i; k--)
+                found.add(list[k]);
+        }
+        return [...found].sort((a, b) => a - b);
+    };
+}
+//# sourceMappingURL=overlap-index.js.map