hippo-memory 1.70.0 → 1.72.0

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,19 +1,24 @@
 // 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 '../util/request-scope.js';
+import { MAX_BODY_BYTES } from '../util/http-util.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) {
     process.stdout.write(JSON.stringify(msg) + '\n');
 }
 // ── Stdio transport ──
-let buffer = Buffer.alloc(0);
+let pending = [];
+let pendingBytes = 0;
+// Set when the pending bytes hold a Content-Length header whose body has not fully arrived.
+let needs;
 // The part of a refused frame still on its way, dropped as it arrives so it is never buffered or read as a new frame.
 let refused = 0;
 function withoutRefused(chunk) {
@@ -61,6 +66,40 @@ 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,29 +116,40 @@ 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.error(`mcp: ${callName(req)} failed after its timeout reply: ${errorMessage(err)}`, errorFields(err));
+        else
+            send(mcpErrorResponse(req.id, err, undefined, callName(req)));
     }));
 }
-/**
- * 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)]);
+    process.stdin.on('data', (raw) => {
+        const chunk = withoutRefused(raw);
+        pending.push(chunk);
+        pendingBytes += chunk.length;
+        // Joining on every chunk would copy the whole pending frame each time; wait until a frame can have ended.
+        if (needs === undefined ? !chunk.includes(0x0a) && pendingBytes <= MAX_BODY_BYTES : pendingBytes < needs)
+            return;
+        let buffer = Buffer.concat(pending, pendingBytes);
+        needs = undefined;
         while (true) {
             const result = parseFrame(buffer);
-            if (result.kind === 'incomplete')
+            if (result.kind === 'incomplete') {
+                needs = result.needs;
                 break;
+            }
             buffer = result.rest;
             if (result.kind === 'oversize') {
                 refused = result.remainder;
@@ -111,6 +161,8 @@ export function startStdioLoop() {
             if (result.kind === 'message')
                 runWithRequestId(randomUUID(), () => dispatch(result.body));
         }
+        pending = buffer.length > 0 ? [buffer] : [];
+        pendingBytes = buffer.length;
     });
     process.stdin.on('end', () => { void exitWhenDrained(); });
     installCrashHandlers('mcp');

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.
+import { truncateWithEllipsis } from '../util/ellipsize.js';
 const ARG_PREVIEW_CHARS = 40;
 function isArgString(v) {
     return typeof v === 'string';
@@ -24,7 +25,7 @@ function describeValue(v) {
     if (Array.isArray(v))
         return 'array';
     if (isArgString(v))
-        return JSON.stringify(v.length > ARG_PREVIEW_CHARS ? `${v.slice(0, ARG_PREVIEW_CHARS)}...` : v);
+        return JSON.stringify(truncateWithEllipsis(v, ARG_PREVIEW_CHARS));
     if (isArgNumber(v) || isArgBoolean(v))
         return String(v);
     return 'object';

package/dist/mcp/tools.js

@@ -1,16 +1,18 @@
 // Tool definitions and input schemas served by tools/list.
 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 { MAX_ID_LEN, MAX_LIST_LIMIT } from '../util/limits.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;
-// Same ceiling as the HTTP list routes' parseListLimit.
-const MAX_LIST_LIMIT = 1000;
 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 session handoff, and recent session events as a "## Continuity" appendix.',
+        description: 'Retrieve relevant memories from the project memory store. Returns memories ranked by relevance, strength, and recency within the token budget. Use ' +
+            'at session start or when you need context about a topic. Pass include_continuity=true to also surface the active task snapshot, latest matching ' +
+            'session handoff, and recent session events as a "## Continuity" appendix.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -27,28 +29,37 @@ export const TOOLS = [
                 },
                 scope: {
                     type: 'string',
-                    description: 'Restrict results and continuity to memories/rows matching this scope exactly. When omitted, default-deny applies to ANY <source>:private:* (slack, github, ...) and unknown-legacy rows.',
+                    description: 'Restrict results and continuity to memories/rows matching this scope exactly. When omitted, default-deny applies to ANY ' +
+                        '<source>:private:* (slack, github, ...) and unknown-legacy rows.',
                 },
                 fresh_tail_count: {
                     type: 'number',
-                    description: 'When > 0, surface the last N kind=raw rows tagged isFreshTail=true regardless of query match. Useful for "what did I just see" continuity. Capped at 200.',
+                    description: 'When > 0, surface the last N kind=raw rows tagged isFreshTail=true regardless of query match. Useful for "what did I just see" ' +
+                        'continuity. Capped at 200.',
                 },
                 fresh_tail_session_id: {
                     type: 'string',
-                    description: 'Restrict the fresh-tail window to a specific session. Without this, fresh-tail is tenant-wide (legacy v1.5.2 behaviour, pre-v1.6.3 default).',
+                    description: 'Restrict the fresh-tail window to a specific session. Without this, fresh-tail is tenant-wide (legacy v1.5.2 behaviour, pre-v1.6.3 ' +
+                        'default).',
                 },
                 summarize_overflow: {
                     type: 'boolean',
-                    description: 'When true (default), entries that overflow the limit and share a level-2 parent summary cause that summary to be appended in their place. Set false for strict-limit behaviour.',
+                    description: 'When true (default), entries that overflow the limit and share a level-2 parent summary cause that summary to be appended in their ' +
+                        'place. Set false for strict-limit behaviour.',
                 },
                 scorer_window: {
                     type: 'number',
-                    description: 'How many of the top-ranked memories the fresh-tail and summarize-overflow appendix is worked out against. The main list ranks the whole tenant store, so scorer_window does not narrow it. Default 200. Rejected as RecallContractError code=invalid_scorer_window if 0/negative/non-finite/non-numeric.',
+                    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',
                     maxLength: MAX_ID_LEN,
-                    description: `Optional session id (v1.7.4). When set AND (tenant, session) has active goals, applies the dlPFC goal-stack boost to the ranked memories before formatting. Mirrors fresh_tail_session_id shape (${MAX_ID_LEN}-char cap).`,
+                    description: `Optional session id (v1.7.4). When set AND (tenant, session) has active goals, ` +
+                        `applies the dlPFC goal-stack boost to the ranked memories before formatting. ` +
+                        `Mirrors fresh_tail_session_id shape (${MAX_ID_LEN}-char cap).`,
                 },
             },
             required: ['query'],
@@ -56,7 +67,9 @@ 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. Tenant-scoped; default-deny on private scopes.',
+        description: 'Build a chronologically-ordered context window for a session. Returns ordered items: fresh-tail raw rows + level-2 summary substitutions for older ' +
+            'rows + budget-fit. Hippo-additive vs lossless-claw: eviction picks lowest-strength non-fresh-tail items first instead of oldest-first. ' +
+            'Tenant-scoped; default-deny on private scopes.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -80,7 +93,8 @@ export const TOOLS = [
                 },
                 scope: {
                     type: 'string',
-                    description: 'Restrict to memories whose scope matches exactly. When omitted, default-deny applies to ANY <source>:private:* scope and unknown:legacy rows. Pass an explicit scope to assemble a private session with consent.',
+                    description: 'Restrict to memories whose scope matches exactly. When omitted, default-deny applies to ANY <source>:private:* scope and ' +
+                        'unknown:legacy rows. Pass an explicit scope to assemble a private session with consent.',
                 },
             },
             required: ['session_id'],
@@ -88,7 +102,8 @@ 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: {
@@ -112,7 +127,8 @@ export const TOOLS = [
                     type: 'integer',
                     minimum: 1,
                     maximum: 10,
-                    description: 'v0.30 / E5: walk N levels down (default 1 = direct children only). Higher values include children of children. Token budget remains GLOBAL across levels. Hard cap 10.',
+                    description: 'v0.30 / E5: walk N levels down (default 1 = direct children only). Higher values include children of children. Token budget remains ' +
+                        'GLOBAL across levels. Hard cap 10.',
                 },
             },
             required: ['summary_id'],
@@ -120,7 +136,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. Errors get 2x half-life.',
+        description: 'Store a new memory. Use when you learn something non-obvious, hit an error, or discover a useful pattern. Memories decay over time unless retrieved. ' +
+            'Errors get 2x half-life.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -131,14 +148,16 @@ 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. 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: {
@@ -152,7 +171,9 @@ 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 no-scope caller does NOT see ANY <source>:private:* (slack, github, ...) or legacy-quarantine rows.',
+        description: 'Smart context injection: auto-detects current task from git state and returns relevant memories plus the active task snapshot, session handoff and ' +
+            'recent session trail (the same bundle as GET /v1/context). Use at the start of any session. Memories and those sections are scope-filtered: a ' +
+            'no-scope caller does NOT see ANY <source>:private:* (slack, github, ...) or legacy-quarantine rows.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -160,11 +181,12 @@ 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',
-                    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.',
+                    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.',
                 },
             },
         },
@@ -232,13 +254,16 @@ 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 + mean actual + mean ratio + median ratio + MAE + a human-readable summary. Tenant-scoped.',
+        description: 'J3 reference-class / planning-fallacy detector. Get base-rate stats for closed predictions in a class. Call this when you make a forward-looking ' +
+            'claim (effort estimate, rollout risk, deadline) to anchor on the past track record rather than the inside view. Returns count + mean estimate + ' +
+            'mean actual + mean ratio + median ratio + MAE + a human-readable summary. Tenant-scoped.',
         inputSchema: {
             type: 'object',
             properties: {
                 class_tag: {
                     type: 'string',
-                    description: 'Cohort label, e.g. "migration-effort", "rollout-risk", "deadline-week". Must match the class_tag used when the predictions were created via hippo_predict (or `hippo predict ...`).',
+                    description: 'Cohort label, e.g. "migration-effort", "rollout-risk", "deadline-week". Must match the class_tag used when the predictions were ' +
+                        'created via hippo_predict (or `hippo predict ...`).',
                 },
             },
             required: ['class_tag'],

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

@@ -1,27 +1,9 @@
-/**
- * customer_note first-class object.
- *
- * A `customer_note` is a discrete note recorded against an account/customer entity:
- * a `note` body scoped to a `customer`, evolving via the supersede delta lifecycle.
- * Entity-scoping is a free-form `customer` column (the `entities` table is unbuilt,
- * so an FK is deferred). Unlike project_brief's one-summary-per-repo,
- * a customer accrues MANY discrete notes over time, each with its own supersede chain
- * (correct a note -> a new version preserving history; close retires it).
- *
- * Reuses the project_brief/skill supersede machinery verbatim (superseded_by self-FK
- * + CAS + INSERT-preflight + server-derived version + change_summary + supersede
- * tenant-match trigger). It has NO assembler/renderer (the simplest first-class object): the
- * contribution is purely the entity-scoping dimension.
- *
- * The `customer_notes` table is the source of truth (survives memory decay); the
- * memory mirror is for recall. memory_id is NULLABLE with ON DELETE SET NULL.
- *
- * Lifecycle: active -> superseded (a corrected version) or active -> closed (retired).
- */
+/** customer_note object: many discrete notes per free-form `customer` column (no entities FK yet), each with its own supersede chain.
+ *  The `customer_notes` table is the source of truth; the memory mirror (memory_id NULLABLE, ON DELETE SET NULL) is for recall. */
 import type { KeysetPosition } from '../util/keyset.js';
 import type { SavableDescriptor } from './descriptor.js';
-import type { CustomerNote, NoteStatus } from '../store/object-types.js';
-export type { CustomerNote, NoteStatus } from '../store/object-types.js';
+import type { CustomerNote, NoteStatus } from '../core/object-types.js';
+export type { CustomerNote, NoteStatus } from '../core/object-types.js';
 export declare const VALID_NOTE_STATES: ReadonlySet<NoteStatus>;
 /** Field caps (untrusted at the HTTP/SDK boundary). note is a body, so a larger cap
  *  than the 4096 short-field convention. */
@@ -47,32 +29,15 @@ export interface ListCustomerNotesOpts {
     after?: KeysetPosition;
 }
 export declare const CUSTOMER_NOTE: SavableDescriptor<'customer_note', SaveCustomerNoteOpts>;
-/**
- * Create a customer_note (or a new version that supersedes an existing one). Writes
- * the memory mirror + the customer_notes row in the `objects` store group's one transaction.
- * When supersedesNoteId is given, the referenced ACTIVE row is preflighted (status +
- * version) BEFORE the INSERT, then CAS-UPDATEd -> superseded in the same transaction;
- * the new version = predecessor.version + 1 (server-derived).
- *
- * The memory mirror carries a `customer:<lc>` tag (in addition to ['customer_note']
- * + caller extraTags) so scope-aware recall treats the note as entity-local. There is
- * no self-recursion path (customer_note has no receipt-query/refresh).
- */
+/** Create a customer_note, or a new version superseding an existing one, in the `objects` store group's one transaction.
+ *  The mirror carries a `customer:<lc>` tag so scope-aware recall treats the note as entity-local. */
 export declare function saveCustomerNote(hippoRoot: string, tenantId: string, opts: SaveCustomerNoteOpts, actor?: string): CustomerNote;
-/**
- * Close (retire) an active note. CAS guard WHERE status='active'; 0 changes
- * distinguishes not-found from not-active. A superseded row is terminal.
- */
+/** Close (retire) an active note; CAS on status='active', 0 changes means not-found or not-active. */
 export declare function closeCustomerNote(hippoRoot: string, tenantId: string, id: number, actor?: string): CustomerNote;
 export declare function loadCustomerNoteById(hippoRoot: string, tenantId: string, id: number): CustomerNote | null;
 export declare function loadCustomerNotes(hippoRoot: string, tenantId: string, opts?: ListCustomerNotesOpts): CustomerNote[];
-/**
- * All ACTIVE notes for a customer, newest first. Returns a LIST (a customer accrues
- * MANY notes) - this deliberately DIVERGES from project_brief's
- * loadActiveBriefForRepo, which returns a single brief-or-null because a repo has one
- * evolving summary. A future caller cloning the project_brief shape by analogy must
- * not assume a single-return here; the plural name signals the list contract.
- */
+/** All ACTIVE notes for a customer, newest first. Returns a LIST, unlike project_brief's single-or-null
+ *  loadActiveBriefForRepo: a customer accrues many notes. */
 export declare function loadActiveNotesForCustomer(hippoRoot: string, tenantId: string, customer: string, opts?: {
     limit?: number;
 }): CustomerNote[];

package/dist/objects/customer-notes.js

@@ -1,28 +1,7 @@
-/**
- * customer_note first-class object.
- *
- * A `customer_note` is a discrete note recorded against an account/customer entity:
- * a `note` body scoped to a `customer`, evolving via the supersede delta lifecycle.
- * Entity-scoping is a free-form `customer` column (the `entities` table is unbuilt,
- * so an FK is deferred). Unlike project_brief's one-summary-per-repo,
- * a customer accrues MANY discrete notes over time, each with its own supersede chain
- * (correct a note -> a new version preserving history; close retires it).
- *
- * Reuses the project_brief/skill supersede machinery verbatim (superseded_by self-FK
- * + CAS + INSERT-preflight + server-derived version + change_summary + supersede
- * tenant-match trigger). It has NO assembler/renderer (the simplest first-class object): the
- * contribution is purely the entity-scoping dimension.
- *
- * The `customer_notes` table is the source of truth (survives memory decay); the
- * memory mirror is for recall. memory_id is NULLABLE with ON DELETE SET NULL.
- *
- * Lifecycle: active -> superseded (a corrected version) or active -> closed (retired).
- */
+/** 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';
-// ---------------------------------------------------------------------------
-// Domain types
-// ---------------------------------------------------------------------------
 export const VALID_NOTE_STATES = new Set([
     'active',
     'superseded',
@@ -69,27 +48,12 @@ export const CUSTOMER_NOTE = {
         };
     },
 };
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/**
- * Create a customer_note (or a new version that supersedes an existing one). Writes
- * the memory mirror + the customer_notes row in the `objects` store group's one transaction.
- * When supersedesNoteId is given, the referenced ACTIVE row is preflighted (status +
- * version) BEFORE the INSERT, then CAS-UPDATEd -> superseded in the same transaction;
- * the new version = predecessor.version + 1 (server-derived).
- *
- * The memory mirror carries a `customer:<lc>` tag (in addition to ['customer_note']
- * + caller extraTags) so scope-aware recall treats the note as entity-local. There is
- * no self-recursion path (customer_note has no receipt-query/refresh).
- */
+/** 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);
 }
-/**
- * Close (retire) an active note. CAS guard WHERE status='active'; 0 changes
- * distinguishes not-found from not-active. A superseded row is terminal.
- */
+/** 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);
 }
@@ -99,13 +63,8 @@ export function loadCustomerNoteById(hippoRoot, 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 });
 }
-/**
- * All ACTIVE notes for a customer, newest first. Returns a LIST (a customer accrues
- * MANY notes) - this deliberately DIVERGES from project_brief's
- * loadActiveBriefForRepo, which returns a single brief-or-null because a repo has one
- * evolving summary. A future caller cloning the project_brief shape by analogy must
- * not assume a single-return here; the plural name signals the list contract.
- */
+/** 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 });
 }

package/dist/objects/decisions.d.ts

@@ -1,38 +1,16 @@
-/**
- * Decision first-class object.
- *
- * `hippo decide` used to write only a tagged memory (tags ['decision'], source
- * 'decision') with a 90-day half-life, so an in-force decision decayed out of
- * recall even though it was never reversed. The `decisions` table is now the
- * source of truth: a decision stays `active` regardless of memory decay, and
- * `hippo decide list --status active` is authoritative. A memory row still
- * mirrors the decision for recall surfaces but is NOT canonical — memory_id is
- * NULLABLE with ON DELETE SET NULL so forget/consolidate/archive gracefully
- * orphans the decision row.
- *
- * Lifecycle: active -> superseded (a newer decision replaces it; superseded_by
- * points to the successor) or active -> closed (retired with no successor).
- *
- * Tenant scoping: every helper requires tenantId. BEFORE INSERT/UPDATE triggers
- * enforce decisions.tenant_id == the referenced memory's tenant_id, and a
- * superseded_by same-tenant trigger makes cross-tenant supersession
- * unrepresentable. Mirrors the predictions pattern (src/predictions.ts).
- *
- * Dual-write atomicity: `saveDecision` hands the memory and the decision to the
- * `objects` store group, which commits them (and, when superseding, the old
- * row's UPDATE) together, so a failure in any step rolls all of them back.
- */
+/** 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 { SavableDescriptor } from './descriptor.js';
-import type { Decision, DecisionStatus } from '../store/object-types.js';
-export type { Decision, DecisionStatus } from '../store/object-types.js';
+import type { Decision, DecisionStatus } from '../core/object-types.js';
+export type { Decision, DecisionStatus } from '../core/object-types.js';
 export declare const VALID_DECISION_STATES: ReadonlySet<DecisionStatus>;
 export interface SaveDecisionOpts {
     decisionText: string;
     context?: string;
-    /** Table id of an ACTIVE decision this one supersedes. The CLI resolves it
-     *  from a `--supersedes <memory-id>` via resolveActiveDecisionIdByMemory;
-     *  HTTP/SDK pass the table id directly. */
+    /** Table id of an ACTIVE decision this one supersedes; the CLI resolves a `--supersedes <memory-id>`
+     *  via resolveActiveDecisionIdByMemory, HTTP/SDK pass the table id. */
     supersedesDecisionId?: number;
     /** Extra memory tags merged after ['decision'] (the CLI passes path-context
      *  tags; HTTP/SDK pass none). */
@@ -45,35 +23,19 @@ export interface ListDecisionsOpts {
     after?: KeysetPosition;
 }
 export declare const DECISION: SavableDescriptor<'decision', SaveDecisionOpts>;
-/**
- * Create a decision. The memory mirror and the decisions row are written in
- * one transaction by the `objects` store group. When supersedesDecisionId is
- * given, the referenced ACTIVE row is UPDATEd -> superseded in the SAME
- * transaction (CAS: WHERE status='active'; zero rows changed means a duplicate
- * supersede aborts the whole write rather than orphaning a successor).
- *
- * The memory mirror preserves the legacy `hippo decide` shape: tags
- * ['decision', ...extraTags], source 'decision', confidence 'verified',
- * the configured default half-life, content = "<text>\n\nContext: <context>"
- * when context is given (so existing recall output is unchanged).
- */
+/** 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;
-/**
- * Close (retire) an active decision with no successor. Updates the decisions
- * row only; the memory mirror is not mutated.
- */
+/** 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?: {
     limit?: number;
 }): Decision[];
-/**
- * Resolve a `--supersedes <memory-id>` (the legacy CLI contract) to the table id
- * of the ACTIVE decision backed by that memory, or null when the memory has no
- * active decision row (a legacy pre-episode decision-tagged memory). Extracted
- * so the CLI's backward-compat path is unit-testable at the store layer without
- * exporting cmdDecide.
- */
+/** 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;
 //# sourceMappingURL=decisions.d.ts.map