hippo-memory 1.72.0 → 2.1.0

package/dist/mcp/shared-gate.js

@@ -8,9 +8,10 @@ const OFF_ON_SHARED = new Map([
     ['hippo_peers', "lists the server's own global store, not the repos that share this one"],
 ]);
 const OPEN_WITHOUT_PROJECT = new Set(['hippo_predict_baserate']);
-/** The refusal text for this call, or undefined when it may run; stdio passes no context and is never gated. */
+/** The refusal text for this call, or undefined when it may run; the stdio host is the operator's own process and is
+ * never gated. */
 export function sharedStoreRefusal(name, ctx) {
-    if (ctx === undefined || !isSharedStore(ctx.hippoRoot))
+    if (ctx.stdio === true || !isSharedStore(ctx.hippoRoot))
         return undefined;
     const off = OFF_ON_SHARED.get(name);
     if (off !== undefined)

package/dist/mcp/stdio.d.ts

@@ -1,4 +1,7 @@
-/** 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;
+import { type McpHost } from './protocol.js';
+/** 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. The caller picks
+ * the host, so src/mcp names no store adapter and no scope plumbing. */
+export declare function startStdioLoop(host: McpHost): void;
 //# sourceMappingURL=stdio.d.ts.map

package/dist/mcp/stdio.js

@@ -4,13 +4,15 @@ import { errorFields, errorMessage, log } from '../util/log.js';
 import { requestDeadlineMs } from '../util/request-scope.js';
 import { MAX_BODY_BYTES } from '../util/http-util.js';
 import { parseFrame } from './framing.js';
-import { mcpErrorResponse } from './protocol.js';
+import { findHippoRoot, mcpErrorResponse } from './protocol.js';
+import { resolveTenantId } from '../store/tenant.js';
+import { getGlobalRoot, initGlobal } from '../sharing/global-store.js';
 import { handleMcpRequest } from './request.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
+// MCP stdio transport spec: messages are newline-delimited JSON-RPC, no embedded
+// newlines. https://modelcontextprotocol.io/specification/.../basic/transports#stdio
 function send(msg) {
     process.stdout.write(JSON.stringify(msg) + '\n');
 }
@@ -37,7 +39,8 @@ function withoutRefused(chunk) {
 function isRoutableRequest(v) {
     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. */
+/** 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)) {
@@ -46,7 +49,8 @@ function answerUnroutable(frame) {
     }
     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. */
+/** 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();
@@ -73,9 +77,9 @@ 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) {
+/** 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, abort) {
     const ms = requestDeadlineMs();
     if (ms === 0)
         return () => false;
@@ -83,7 +87,10 @@ function watchDeadline(req, owedReply) {
     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 });
+        log.warn(`mcp: ${name} did not answer within ${ms} ms; its next step is cancelled and its reply will be dropped`, {
+            method: req.method,
+        });
+        abort.abort(new DOMException(`${name} did not finish within ${ms} ms`, 'TimeoutError'));
         if (!owedReply)
             return;
         const requestId = currentRequestId();
@@ -100,13 +107,30 @@ function watchDeadline(req, owedReply) {
         return expired;
     };
 }
-function dispatch(body) {
+/** 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 wins. */
+function createGlobalStoreOnFirstRun() {
+    initGlobal();
+    const root = getGlobalRoot();
+    log.warn(`no memory store found; created the global store at ${root}. Run \`hippo init\` in a project for a project store.`);
+    return root;
+}
+/** Runs one frame in the host's scope; only a tool call builds a context, so tools/list never creates a store. */
+function handleFrame(req, host) {
+    return host.runRequest(() => {
+        if (req.method !== 'tools/call')
+            return handleMcpRequest(req, undefined);
+        const root = findHippoRoot() ?? createGlobalStoreOnFirstRun();
+        return handleMcpRequest(req, host.contextFor(root, resolveTenantId({})));
+    });
+}
+function dispatch(body, abort, host) {
     let parsed;
     try {
         parsed = JSON.parse(body);
     }
-    catch {
-        log.debug('mcp: answered a frame that is not valid JSON with a parse error');
+    catch (err) {
+        log.debug('mcp: answered a frame that is not valid JSON with a parse error', errorFields(err));
         send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
         return;
     }
@@ -116,25 +140,35 @@ function dispatch(body) {
     }
     const req = parsed;
     if (req.method.startsWith('notifications/')) {
-        const stopWatching = watchDeadline(req, false);
-        track(req.method, handleMcpRequest(req).then(() => { }).catch((err) => {
+        const stopWatching = watchDeadline(req, false, abort);
+        track(req.method, handleFrame(req, host).then(() => { }).catch((err) => {
             log.error(`mcp notification ${req.method} failed: ${errorMessage(err)}`, errorFields(err));
         }).finally(stopWatching));
         return;
     }
     // 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) => {
-        if (timedOut())
+    const timedOut = watchDeadline(req, isJsonString(req.id) || isJsonNumber(req.id), abort);
+    track(req.method, handleFrame(req, host)
+        .then((resp) => {
+        if (!timedOut() && resp)
+            send(resp);
+    })
+        .catch((err) => {
+        if (timedOut() && err instanceof DOMException && err.name === 'TimeoutError') {
+            log.debug(`mcp: ${callName(req)} stopped at its deadline`, errorFields(err));
+        }
+        else if (timedOut()) {
             log.error(`mcp: ${callName(req)} failed after its timeout reply: ${errorMessage(err)}`, errorFields(err));
+        }
         else
             send(mcpErrorResponse(req.id, err, undefined, callName(req)));
     }));
 }
-/** 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() {
+/** 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. The caller picks
+ * the host, so src/mcp names no store adapter and no scope plumbing. */
+export function startStdioLoop(host) {
     process.stdin.on('data', (raw) => {
         const chunk = withoutRefused(raw);
         pending.push(chunk);
@@ -158,8 +192,10 @@ export function startStdioLoop() {
                 continue;
             }
             // One id per frame, so the error reply and every line logged for the call name the same request.
-            if (result.kind === 'message')
-                runWithRequestId(randomUUID(), () => dispatch(result.body));
+            if (result.kind === 'message') {
+                const abort = new AbortController();
+                runWithRequestId(randomUUID(), () => dispatch(result.body, abort, host), undefined, abort.signal);
+            }
         }
         pending = buffer.length > 0 ? [buffer] : [];
         pendingBytes = buffer.length;

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

@@ -16,6 +16,9 @@ export interface ToolInputSchema {
     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. */
+/**
+ * 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

@@ -1,4 +1,5 @@
-// Hand-written for the JSON Schema subset the hippo tool definitions use, so the MCP server needs no validator dependency.
+// Hand-written for the JSON Schema subset the hippo tool definitions use, so the MCP server needs no validator
+// dependency.
 import { truncateWithEllipsis } from '../util/ellipsize.js';
 const ARG_PREVIEW_CHARS = 40;
 function isArgString(v) {
@@ -11,7 +12,8 @@ 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.
+// 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;
@@ -63,7 +65,10 @@ function checkProperty(name, schema, raw) {
     }
     return null;
 }
-/** One message per violation; undeclared properties pass, and `checkedDownstream` names keep the API layer's own error contract. */
+/**
+ * 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 ?? []) {

package/dist/mcp/tools.js

@@ -10,8 +10,10 @@ const MAX_BUDGET_TOKENS = 25 * DEFAULT_RECALL_BUDGET;
 export const TOOLS = [
     {
         name: 'hippo_recall',
-        description: 'Retrieve relevant memories from the project memory store. Returns memories ranked by relevance, strength, and recency within the token budget. Use ' +
-            'at session start or when you need context about a topic. Pass include_continuity=true to also surface the active task snapshot, latest matching ' +
+        description: 'Retrieve relevant memories from the project memory store. Returns memories ranked by relevance, strength, and ' +
+            'recency within the token budget. Use ' +
+            'at session start or when you need context about a topic. Pass include_continuity=true to also surface the ' +
+            'active task snapshot, latest matching ' +
             'session handoff, and recent session events as a "## Continuity" appendix.',
         inputSchema: {
             type: 'object',
@@ -21,35 +23,44 @@ export const TOOLS = [
                     type: 'number',
                     minimum: 0,
                     maximum: MAX_BUDGET_TOKENS,
-                    description: `Max tokens to return (default: config.defaultBudget, ${DEFAULT_RECALL_BUDGET}; max ${MAX_BUDGET_TOKENS})`,
+                    description: `Max tokens to return (default: config.defaultBudget, ${DEFAULT_RECALL_BUDGET}; 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.',
+                    description: 'Append continuity context (active snapshot + handoff + last 5 session events) below the memory results. ' +
+                        'Useful at session boot.',
                 },
                 scope: {
                     type: 'string',
-                    description: 'Restrict results and continuity to memories/rows matching this scope exactly. When omitted, default-deny applies to ANY ' +
+                    description: 'Restrict results and continuity to memories/rows matching this scope exactly. When omitted, ' +
+                        'default-deny ' +
+                        'applies to ANY ' +
                         '<source>:private:* (slack, github, ...) and unknown-legacy rows.',
                 },
                 fresh_tail_count: {
                     type: 'number',
-                    description: 'When > 0, surface the last N kind=raw rows tagged isFreshTail=true regardless of query match. Useful for "what did I just see" ' +
+                    description: 'When > 0, surface the last N kind=raw rows tagged isFreshTail=true regardless of query match. Useful ' +
+                        'for ' +
+                        '"what did I just see" ' +
                         'continuity. Capped at 200.',
                 },
                 fresh_tail_session_id: {
                     type: 'string',
-                    description: 'Restrict the fresh-tail window to a specific session. Without this, fresh-tail is tenant-wide (legacy v1.5.2 behaviour, pre-v1.6.3 ' +
+                    description: 'Restrict the fresh-tail window to a specific session. Without this, fresh-tail is tenant-wide (legacy ' +
+                        'v1.5.2 behaviour, pre-v1.6.3 ' +
                         'default).',
                 },
                 summarize_overflow: {
                     type: 'boolean',
-                    description: 'When true (default), entries that overflow the limit and share a level-2 parent summary cause that summary to be appended in their ' +
+                    description: 'When true (default), entries that overflow the limit and share a level-2 parent summary cause that ' +
+                        'summary to be appended in their ' +
                         'place. Set false for strict-limit behaviour.',
                 },
                 scorer_window: {
                     type: 'number',
-                    description: `How many of the top-ranked memories the fresh-tail and summarize-overflow appendix is worked out against. ` +
+                    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.`,
@@ -67,8 +78,10 @@ export const TOOLS = [
     },
     {
         name: 'hippo_assemble',
-        description: 'Build a chronologically-ordered context window for a session. Returns ordered items: fresh-tail raw rows + level-2 summary substitutions for older ' +
-            'rows + budget-fit. Hippo-additive vs lossless-claw: eviction picks lowest-strength non-fresh-tail items first instead of oldest-first. ' +
+        description: 'Build a chronologically-ordered context window for a session. Returns ordered items: fresh-tail raw rows + ' +
+            'level-2 summary substitutions for older ' +
+            'rows + budget-fit. Hippo-additive vs lossless-claw: eviction picks lowest-strength non-fresh-tail items first ' +
+            'instead of oldest-first. ' +
             'Tenant-scoped; default-deny on private scopes.',
         inputSchema: {
             type: 'object',
@@ -81,7 +94,8 @@ export const TOOLS = [
                     type: 'number',
                     minimum: 0,
                     maximum: MAX_BUDGET_TOKENS,
-                    description: `Token budget for the assembled context (default ${DEFAULT_ASSEMBLE_BUDGET}; max ${MAX_BUDGET_TOKENS}). Eviction kicks in over budget.`,
+                    description: `Token budget for the assembled context (default ${DEFAULT_ASSEMBLE_BUDGET}; max ` +
+                        `${MAX_BUDGET_TOKENS}). Eviction kicks in over budget.`,
                 },
                 fresh_tail_count: {
                     type: 'number',
@@ -89,11 +103,13 @@ export const TOOLS = [
                 },
                 summarize_older: {
                     type: 'boolean',
-                    description: 'When true (default), older raws sharing a level-2 parent summary get substituted. Set false to keep every older raw as-is.',
+                    description: 'When true (default), older raws sharing a level-2 parent summary get substituted. Set false to keep ' +
+                        'every older raw as-is.',
                 },
                 scope: {
                     type: 'string',
-                    description: 'Restrict to memories whose scope matches exactly. When omitted, default-deny applies to ANY <source>:private:* scope and ' +
+                    description: 'Restrict to memories whose scope matches exactly. When omitted, default-deny applies to ANY ' +
+                        '<source>:private:* scope and ' +
                         'unknown:legacy rows. Pass an explicit scope to assemble a private session with consent.',
                 },
             },
@@ -102,14 +118,17 @@ export const TOOLS = [
     },
     {
         name: 'hippo_drill',
-        description: 'Walk one step down the DAG from a level-2+ topic summary to its direct children. Companion to hippo_recall: when recall returns an item with ' +
-            'isSummary=true and substitutedFor=[ids], pass the summary id here to recover the original detail. Tenant-scoped; default-deny on private scopes.',
+        description: 'Walk one step down the DAG from a level-2+ topic summary to its direct children. Companion to hippo_recall: ' +
+            'when recall returns an item with ' +
+            'isSummary=true and substitutedFor=[ids], pass the summary id here to recover the original detail. ' +
+            'Tenant-scoped; default-deny on private scopes.',
         inputSchema: {
             type: 'object',
             properties: {
                 summary_id: {
                     type: 'string',
-                    description: 'ID of the level-2 (or higher) summary to drill into. Must be a summary, not a leaf — leaves are not drillable.',
+                    description: 'ID of the level-2 (or higher) summary to drill into. Must be a summary, not a leaf — leaves are not ' +
+                        'drillable.',
                 },
                 limit: {
                     type: 'number',
@@ -121,13 +140,15 @@ export const TOOLS = [
                     type: 'number',
                     minimum: 0,
                     maximum: MAX_BUDGET_TOKENS,
-                    description: `Max total token cost (~ chars/4) of returned children (max ${MAX_BUDGET_TOKENS}). Truncates chronologically.`,
+                    description: `Max total token cost (~ chars/4) of returned children (max ${MAX_BUDGET_TOKENS}). Truncates ` +
+                        `chronologically.`,
                 },
                 depth: {
                     type: 'integer',
                     minimum: 1,
                     maximum: 10,
-                    description: 'v0.30 / E5: walk N levels down (default 1 = direct children only). Higher values include children of children. Token budget remains ' +
+                    description: 'v0.30 / E5: walk N levels down (default 1 = direct children only). Higher values include children of ' +
+                        'children. Token budget remains ' +
                         'GLOBAL across levels. Hard cap 10.',
                 },
             },
@@ -136,7 +157,8 @@ export const TOOLS = [
     },
     {
         name: 'hippo_remember',
-        description: 'Store a new memory. Use when you learn something non-obvious, hit an error, or discover a useful pattern. Memories decay over time unless retrieved. ' +
+        description: 'Store a new memory. Use when you learn something non-obvious, hit an error, or discover a useful pattern. ' +
+            'Memories decay over time unless retrieved. ' +
             'Errors get 2x half-life.',
         inputSchema: {
             type: 'object',
@@ -148,15 +170,22 @@ export const TOOLS = [
                 error: { type: 'boolean', description: 'Mark as error memory (doubles half-life)' },
                 pin: { type: 'boolean', description: 'Pin memory (never decays)' },
                 tag: { type: 'string', description: 'Optional tag for categorization' },
-                personal: { type: 'boolean', description: 'Store it as your own private memory: only you can recall it, in every project. Needs a key you minted or ' +
-                        'a sign-in.' },
+                personal: {
+                    type: 'boolean',
+                    description: 'Store it as your own private memory: only you can recall it, in every project. Needs a key you minted ' +
+                        'or ' +
+                        '' +
+                        'a sign-in.',
+                },
             },
             required: ['text'],
         },
     },
     {
         name: 'hippo_outcome',
-        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 " +
+        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',
@@ -171,8 +200,11 @@ export const TOOLS = [
     },
     {
         name: 'hippo_context',
-        description: 'Smart context injection: auto-detects current task from git state and returns relevant memories plus the active task snapshot, session handoff and ' +
-            'recent session trail (the same bundle as GET /v1/context). Use at the start of any session. Memories and those sections are scope-filtered: a ' +
+        description: 'Smart context injection: auto-detects current task from git state and returns relevant memories plus the ' +
+            'active task snapshot, session handoff and ' +
+            'recent session trail (the same bundle as GET /v1/context). Use at the start of any session. Memories and ' +
+            'those ' +
+            'sections are scope-filtered: a ' +
             'no-scope caller does NOT see ANY <source>:private:* (slack, github, ...) or legacy-quarantine rows.',
         inputSchema: {
             type: 'object',
@@ -181,11 +213,14 @@ export const TOOLS = [
                     type: 'number',
                     minimum: 0,
                     maximum: MAX_BUDGET_TOKENS,
-                    description: `Max tokens (default: config.defaultContextBudget, ${DEFAULT_CONFIG.defaultContextBudget}; max ${MAX_BUDGET_TOKENS})`,
+                    description: `Max tokens (default: config.defaultContextBudget, ${DEFAULT_CONFIG.defaultContextBudget}; ` +
+                        `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:* ' +
+                    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.',
                 },
             },
@@ -226,8 +261,14 @@ export const TOOLS = [
                 conflict_id: { type: 'number', description: 'The conflict ID to resolve' },
                 keep: { type: 'string', description: 'ID of the memory to keep' },
                 forget: { type: 'boolean', description: 'Delete the loser instead of weakening (default: false)' },
-                rejectLoser: { type: 'boolean', description: 'Tombstone the loser\'s value too, so it refuses re-ingestion (implies removal; default: false)' },
-                reason: { type: 'string', description: 'Reason recorded on the tombstone when rejectLoser is set (default: a conflict-context string)' },
+                rejectLoser: {
+                    type: 'boolean',
+                    description: "Tombstone the loser's value too, so it refuses re-ingestion (implies removal; default: false)",
+                },
+                reason: {
+                    type: 'string',
+                    description: 'Reason recorded on the tombstone when rejectLoser is set (default: a conflict-context string)',
+                },
             },
             required: ['conflict_id', 'keep'],
         },
@@ -254,15 +295,18 @@ export const TOOLS = [
     },
     {
         name: 'hippo_predict_baserate',
-        description: 'J3 reference-class / planning-fallacy detector. Get base-rate stats for closed predictions in a class. Call this when you make a forward-looking ' +
-            'claim (effort estimate, rollout risk, deadline) to anchor on the past track record rather than the inside view. Returns count + mean estimate + ' +
+        description: 'J3 reference-class / planning-fallacy detector. Get base-rate stats for closed predictions in a class. Call ' +
+            'this when you make a forward-looking ' +
+            'claim (effort estimate, rollout risk, deadline) to anchor on the past track record rather than the inside ' +
+            'view. Returns count + mean estimate + ' +
             'mean actual + mean ratio + median ratio + MAE + a human-readable summary. Tenant-scoped.',
         inputSchema: {
             type: 'object',
             properties: {
                 class_tag: {
                     type: 'string',
-                    description: 'Cohort label, e.g. "migration-effort", "rollout-risk", "deadline-week". Must match the class_tag used when the predictions were ' +
+                    description: 'Cohort label, e.g. "migration-effort", "rollout-risk", "deadline-week". Must match the class_tag used ' +
+                        'when the predictions were ' +
                         'created via hippo_predict (or `hippo predict ...`).',
                 },
             },

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

@@ -1,6 +1,8 @@
-/** 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. */
+/** 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 { Objects } from '../store/port.js';
 import type { SavableDescriptor } from './descriptor.js';
 import type { CustomerNote, NoteStatus } from '../core/object-types.js';
 export type { CustomerNote, NoteStatus } from '../core/object-types.js';
@@ -29,16 +31,16 @@ export interface ListCustomerNotesOpts {
     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;
+/** 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(objects: Objects, hippoRoot: string, tenantId: string, opts: SaveCustomerNoteOpts, actor?: string): Promise<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[];
+export declare function closeCustomerNote(objects: Objects, tenantId: string, id: number, actor?: string): Promise<CustomerNote>;
+export declare function loadCustomerNoteById(objects: Objects, tenantId: string, id: number): Promise<CustomerNote | null>;
+export declare function loadCustomerNotes(objects: Objects, tenantId: string, opts?: ListCustomerNotesOpts): Promise<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?: {
+export declare function loadActiveNotesForCustomer(objects: Objects, tenantId: string, customer: string, opts?: {
     limit?: number;
-}): CustomerNote[];
+}): Promise<CustomerNote[]>;
 //# sourceMappingURL=customer-notes.d.ts.map

package/dist/objects/customer-notes.js

@@ -1,7 +1,8 @@
-/** 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. */
+/** 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 { checkText, requireLine } from './fields.js';
-import { closeObjectAt, listObjectsAt, objectByIdAt, saveObjectAt } from './lifecycle.js';
+import { closeObject, listObjects, objectById, saveObject } from './lifecycle.js';
 export const VALID_NOTE_STATES = new Set([
     'active',
     'superseded',
@@ -48,24 +49,29 @@ export const CUSTOMER_NOTE = {
         };
     },
 };
-/** 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 function saveCustomerNote(hippoRoot, tenantId, opts, actor = 'cli') {
-    return saveObjectAt(CUSTOMER_NOTE, { hippoRoot, tenantId, actor }, opts);
+/** 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 function saveCustomerNote(objects, hippoRoot, tenantId, opts, actor = 'cli') {
+    return saveObject(objects, CUSTOMER_NOTE, { hippoRoot, tenantId, actor }, opts);
 }
 /** Close (retire) an active note; CAS on status='active', 0 changes means not-found or not-active. */
-export function closeCustomerNote(hippoRoot, tenantId, id, actor = 'cli') {
-    return closeObjectAt(hippoRoot, CUSTOMER_NOTE, tenantId, id, actor);
+export function closeCustomerNote(objects, tenantId, id, actor = 'cli') {
+    return closeObject(objects, CUSTOMER_NOTE, tenantId, id, actor);
 }
-export function loadCustomerNoteById(hippoRoot, tenantId, id) {
-    return objectByIdAt(hippoRoot, CUSTOMER_NOTE, tenantId, id);
+export function loadCustomerNoteById(objects, tenantId, id) {
+    return objectById(objects, CUSTOMER_NOTE, tenantId, id);
 }
-export function loadCustomerNotes(hippoRoot, tenantId, opts = {}) {
-    return listObjectsAt(hippoRoot, CUSTOMER_NOTE, tenantId, { status: opts.status, filter: opts.customer, limit: opts.limit, after: opts.after });
+export function loadCustomerNotes(objects, tenantId, opts = {}) {
+    return listObjects(objects, CUSTOMER_NOTE, tenantId, {
+        status: opts.status,
+        filter: opts.customer,
+        limit: opts.limit,
+        after: opts.after,
+    });
 }
 /** 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 function loadActiveNotesForCustomer(hippoRoot, tenantId, customer, opts = {}) {
-    return loadCustomerNotes(hippoRoot, tenantId, { customer, status: 'active', limit: opts.limit });
+export function loadActiveNotesForCustomer(objects, tenantId, customer, opts = {}) {
+    return loadCustomerNotes(objects, tenantId, { customer, status: 'active', limit: opts.limit });
 }
 //# sourceMappingURL=customer-notes.js.map

package/dist/objects/decisions.d.ts

@@ -1,7 +1,12 @@
-/** Decision object: the `decisions` table is the source of truth, so an in-force decision stays `active` despite memory decay.
- *  The memory mirror (memory_id NULLABLE, ON DELETE SET NULL) is for recall only; saveDecision commits both in one `objects` transaction. */
+/**
+ * Decision object: the `decisions` table is the source of truth, so an
+ * in-force decision stays `active` despite memory decay. The memory
+ * mirror (memory_id NULLABLE, ON DELETE SET NULL) is for recall only;
+ * saveDecision commits both in one `objects` transaction.
+ */
 import type { MemoryEntry } from '../core/memory.js';
 import type { KeysetPosition } from '../util/keyset.js';
+import type { Objects } from '../store/port.js';
 import type { SavableDescriptor } from './descriptor.js';
 import type { Decision, DecisionStatus } from '../core/object-types.js';
 export type { Decision, DecisionStatus } from '../core/object-types.js';
@@ -25,17 +30,20 @@ export interface ListDecisionsOpts {
 export declare const DECISION: SavableDescriptor<'decision', SaveDecisionOpts>;
 /** Create a decision; the memory mirror and the row commit in one transaction.
  *  Superseding CASes the old row (WHERE status='active'), so a duplicate supersede aborts the whole write. */
-export declare function saveDecision(hippoRoot: string, tenantId: string, opts: SaveDecisionOpts, actor?: string): Decision;
-/** Weaken the memory a new decision replaces, once the save has committed: half-life halved to a day at least, marked stale, tagged `superseded`. */
+export declare function saveDecision(objects: Objects, hippoRoot: string, tenantId: string, opts: SaveDecisionOpts, actor?: string): Promise<Decision>;
+/**
+ * Weaken the memory a new decision replaces, once the save has committed: half-life halved to a day at least, marked
+ * stale, tagged `superseded`.
+ */
 export declare function weakenSupersededMemory(hippoRoot: string, entry: MemoryEntry, actor?: string): void;
 /** Close (retire) an active decision with no successor; the memory mirror is not mutated. */
-export declare function closeDecision(hippoRoot: string, tenantId: string, id: number, actor?: string): Decision;
-export declare function loadDecisionById(hippoRoot: string, tenantId: string, id: number): Decision | null;
-export declare function loadDecisions(hippoRoot: string, tenantId: string, opts?: ListDecisionsOpts): Decision[];
-export declare function loadActiveDecisions(hippoRoot: string, tenantId: string, opts?: {
+export declare function closeDecision(objects: Objects, tenantId: string, id: number, actor?: string): Promise<Decision>;
+export declare function loadDecisionById(objects: Objects, tenantId: string, id: number): Promise<Decision | null>;
+export declare function loadDecisions(objects: Objects, tenantId: string, opts?: ListDecisionsOpts): Promise<Decision[]>;
+export declare function loadActiveDecisions(objects: Objects, tenantId: string, opts?: {
     limit?: number;
-}): Decision[];
+}): Promise<Decision[]>;
 /** Resolve a `--supersedes <memory-id>` to the table id of the ACTIVE decision backed by that memory, or null.
  *  Exported so the CLI's backward-compat path is testable at the store layer. */
-export declare function resolveActiveDecisionIdByMemory(hippoRoot: string, tenantId: string, memoryId: string): number | null;
+export declare function resolveActiveDecisionIdByMemory(objects: Objects, tenantId: string, memoryId: string): Promise<number | null>;
 //# sourceMappingURL=decisions.d.ts.map