hippo-memory 1.56.0 → 1.58.0

package/README.md

@@ -559,6 +559,17 @@ are not recorded yet. It holds ids, hashes, counts and reasons only, never promp
 text; the prompt hash is unsalted, so a very short prompt can be guessed. A ledger failure prints one stderr line and never changes what the hook prints. Rows
 older than 90 days are pruned; at a heavy 300 prompts a day that is about 190 MB per store.
 
+**Run a pilot with a holdout group.** Set `{"pilot":{"holdoutRateBp":2000}}` in `.hippo/config.json`
+to hold back memories from about 20% of sessions. The rate is in basis points, 0 to 10000, and 0
+is off (the default). The setting is read from the store the token ledger writes to. A session
+lands in its arm by a hash of its id, and the first hook call writes one row to the token ledger.
+A holdout session gets no memories from the per-prompt hook, the SessionStart hook or compact-resume.
+The agent's own `hippo context` pull is gated in Claude Code only, so a Codex holdout session still
+gets memories from it. Capture still runs. `hippo recall`, the HTTP API and the MCP tools are not gated
+and write no arm row. Agents are told to call the MCP context tool at session start, and those calls
+are not recorded. Set the rate to 0 only after the pilot window closes, because 0 ends every holdout at once.
+`hippo doctor` shows the pilot when it is on.
+
 ---
 
 ### Outcome feedback

package/dist/agent-memories/claude-code.js

@@ -2,7 +2,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { realpathOrResolve } from '../project-identity.js';
-import { isStringValue } from '../capture.js';
+import { isStringValue } from '../capture-contract.js';
 import { isJsonObject } from '../hooks.js';
 import { expandHome, frontmatterField, itemTime, readTextFile, splitFrontmatter } from './files.js';
 import { markdownNotes, readFolderStore, uniqueFolders } from './folder-store.js';

package/dist/agent-memories/gemini.js

@@ -1,7 +1,7 @@
 // Gemini CLI: the "Gemini Added Memories" section of GEMINI.md, and the auto-memory folder that projects.json names.
 import fs from 'node:fs';
 import path from 'node:path';
-import { isStringValue } from '../capture.js';
+import { isStringValue } from '../capture-contract.js';
 import { isJsonObject } from '../hooks.js';
 import { readTextFile, splitFrontmatter } from './files.js';
 import { markdownNotes, readFolderStore } from './folder-store.js';

package/dist/api-errors.d.ts

@@ -0,0 +1,27 @@
+/** Errors whose HTTP status is part of the API contract; the server maps by class, so message text can change freely. */
+export type ApiErrorStatus = 400 | 403 | 404 | 409;
+/** Base class: an error the caller caused, carrying the status the HTTP layer answers with. */
+export declare abstract class ApiError extends Error {
+    abstract readonly status: ApiErrorStatus;
+}
+/** The request cannot be applied as given: bad input, or a state this route reports as 400. */
+export declare class BadRequestError extends ApiError {
+    readonly status = 400;
+    constructor(message: string);
+}
+/** The actor's role or identity does not allow the operation. */
+export declare class ForbiddenError extends ApiError {
+    readonly status = 403;
+    constructor(message: string);
+}
+/** The named row does not exist for this tenant. */
+export declare class NotFoundError extends ApiError {
+    readonly status = 404;
+    constructor(message: string);
+}
+/** The row exists but its current state forbids the change (already superseded, closed, or decided). */
+export declare class ConflictError extends ApiError {
+    readonly status = 409;
+    constructor(message: string);
+}
+//# sourceMappingURL=api-errors.d.ts.map

package/dist/api-errors.js

@@ -0,0 +1,37 @@
+/** Errors whose HTTP status is part of the API contract; the server maps by class, so message text can change freely. */
+/** Base class: an error the caller caused, carrying the status the HTTP layer answers with. */
+export class ApiError extends Error {
+}
+/** The request cannot be applied as given: bad input, or a state this route reports as 400. */
+export class BadRequestError extends ApiError {
+    status = 400;
+    constructor(message) {
+        super(message);
+        this.name = 'BadRequestError';
+    }
+}
+/** The actor's role or identity does not allow the operation. */
+export class ForbiddenError extends ApiError {
+    status = 403;
+    constructor(message) {
+        super(message);
+        this.name = 'ForbiddenError';
+    }
+}
+/** The named row does not exist for this tenant. */
+export class NotFoundError extends ApiError {
+    status = 404;
+    constructor(message) {
+        super(message);
+        this.name = 'NotFoundError';
+    }
+}
+/** The row exists but its current state forbids the change (already superseded, closed, or decided). */
+export class ConflictError extends ApiError {
+    status = 409;
+    constructor(message) {
+        super(message);
+        this.name = 'ConflictError';
+    }
+}
+//# sourceMappingURL=api-errors.js.map

package/dist/api.d.ts

@@ -7,6 +7,8 @@
  * in exactly one place.
  */
 import { type DatabaseSyncLike } from './db.js';
+import { BadRequestError } from './api-errors.js';
+export { ApiError, BadRequestError, ConflictError, ForbiddenError, NotFoundError } from './api-errors.js';
 import { deleteEntry, loadAllEntries, type TaskSnapshot, type SessionEvent } from './store.js';
 import { type RejectedValueRow } from './rejection.js';
 import { type DormantMemory, type ListDormantOpts } from './dormant.js';
@@ -19,7 +21,7 @@ import { auditMemories, type AuditEvent, type AuditOp } from './audit.js';
 import { autoShare } from './shared.js';
 import type { DeliveryObserver } from './delivery-recorder.js';
 import { type ApiKeyListItem } from './auth.js';
-import { type RerankStep } from './search.js';
+import { type RerankStep, type SearchResult } from './search.js';
 import { consolidate } from './consolidate.js';
 import { loadConfig } from './config.js';
 import { deduplicateStore } from './dedupe.js';
@@ -77,14 +79,10 @@ export declare function adminActor(subject: string): Actor;
  *     full-store fallback (codex v1.7.0 diff-pass P1). Validated upfront
  *     so the contract holds.
  */
-export declare class RecallContractError extends Error {
+export declare class RecallContractError extends BadRequestError {
     readonly code: 'fresh_tail_requires_session_id' | 'invalid_scorer_window';
     constructor(code: 'fresh_tail_requires_session_id' | 'invalid_scorer_window', message: string);
 }
-/** The actor's role or identity does not allow the operation. HTTP maps it to 403. */
-export declare class ForbiddenError extends Error {
-    constructor(message: string);
-}
 import { isPrivateScope, passesScopeFilterForRecall } from './recall-scope.js';
 export { isPrivateScope, passesScopeFilterForRecall };
 export { passesCliRecallScopeFilter, ScopeForbiddenError } from './recall-scope.js';
@@ -92,9 +90,8 @@ export type { TokenSummary, TokenSurface, TokenSurfaceSummary } from './token-le
 export type { FailureSummary } from './failure-log.js';
 export { classifyOriginProject } from './project-identity.js';
 /**
- * v39 S4: the secret half of the ambient policy on its own, for surfaces
- * with their own scope semantics (MCP hippo_context's explicit-scope
- * exact-match). A flagged row is only admitted inside its owning project;
+ * v39 S4: the secret half of the ambient policy on its own, for callers
+ * that apply their own scope rule. A flagged row is only admitted inside its owning project;
  * flagged rows with no project origin never ambient-inject.
  */
 export declare function ambientSecretAdmit(e: MemoryEntry, currentProjectName: string): boolean;
@@ -126,6 +123,8 @@ export interface RememberResult {
     quarantined?: {
         reason: string;
     };
+    /** Set only when the content held secret material: untrusted text had it redacted, typed text was stored as sent. */
+    warnings?: string[];
 }
 export declare function remember(ctx: Context, opts: RememberOpts): RememberResult;
 export interface RecallOpts {
@@ -270,16 +269,22 @@ export interface RecallOpts {
      * Mirrors `suppressAvailabilityHint`'s pattern: callers that run their OWN
      * tracing over a DIFFERENT result set must suppress api.recall's copy so
      * the training corpus doesn't get a trace mislabeled as 'api' pipeline
-     * when the caller's actual user-visible results came from elsewhere. The
-     * MCP handler sets this — its primary ranked band comes from a separate
-     * physics/hybrid scorer, not this api.recall call's BM25 band (real MCP
-     * tracing is the reserved 'mcp' pipeline, a follow-up). HTTP / direct SDK
-     * callers leave this unset and get the trace.
+     * when the caller's actual user-visible results came from elsewhere. Under
+     * `showRanked` it also drops the 'mcp' trace of the shown list. HTTP /
+     * direct SDK callers leave this unset and get the trace.
      */
     suppressRecallTrace?: boolean;
     /** Set only by the MCP recall tool, which ranks with its own scorer and drops copies from its own final list: this call
      *  then keeps a memory that a merged row in the same result holds word for word. Other callers leave it unset. */
     keepHeldCopies?: boolean;
+    /** MCP recall only: `retrieve` ranks the whole scoped store and strengthens and traces (pipeline 'mcp') just the ids this returns; `results` stays the window band. */
+    showRanked?: (ranking: StoreRanking, result: RecallResult) => readonly string[];
+}
+/** `ranked`: every scored row, best first, goal boost applied, entries as loaded; `pool`: the store after the scope filter. */
+export interface StoreRanking {
+    ranked: SearchResult[];
+    pool: MemoryEntry[];
+    droppedByScope: number;
 }
 export interface ContinuityBlock {
     activeSnapshot: TaskSnapshot | null;
@@ -946,6 +951,8 @@ export interface ContextOpts {
     limit?: number;
     pinnedOnly?: boolean;
     scope?: string;
+    /** Envelope scope to match exactly, as in `recall`: admits that scope even when private, after the actor's scope check. */
+    exactScope?: string;
     /** With `pinnedOnly`, also inject the N most recent writes that pass the
      *  quality floor (`isContentWorthStoring`, DF3). Filtering happens BEFORE
      *  the take-N, so a caller asking for 5 gets 5 qualifying entries rather