hippo-memory 1.57.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';
@@ -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';
@@ -125,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 {

package/dist/api.js

@@ -7,6 +7,8 @@
  * in exactly one place.
  */
 import { openHippoDb, closeHippoDb } from './db.js';
+import { BadRequestError, ConflictError, ForbiddenError, NotFoundError } from './api-errors.js';
+export { ApiError, BadRequestError, ConflictError, ForbiddenError, NotFoundError } from './api-errors.js';
 import { writeEntry, writeEntryDbOnly, strengthenRetrieved, stampOriginProject, writeEntryMirrors, readEntry, deleteEntry, loadRecallSearchEntries, loadEntriesByIds, loadChildrenOf, loadFreshRawMemories, loadSessionRawMemories, countSessionRawMemories, DEFAULT_SEARCH_CANDIDATE_LIMIT, removeEntryMirrors, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, loadLatestHandoff, listSessionEvents, SNAPSHOT_AMBIENT_MAX_AGE_MS, loadIndex, saveIndex, loadAllEntries, loadAmbientCandidates, updateStats, isInitialized, markSummaryDirtyInTx, auditRejectionRefusal, memoriesBackingObjects, } from './store.js';
 import { RejectedValueError } from './rejection.js';
 import { rejectValue, unrejectValue, listRejectionsForTenant } from './reject-flow.js';
@@ -17,7 +19,7 @@ import { quarantineScopeFor, recordQuarantine, getQuarantineRow, listQuarantineR
 import { summarizeFailures } from './failure-log.js';
 import { formatHandoffEvidenceLine } from './handoff.js';
 import { createMemory, createSuccessor, applyOutcome, calculateStrength, markRetrieved, CHURN_STALE_TAG, COMPACTION_MEMORY_TAG, } from './memory.js';
-import { appendAuditEvent, auditQueryFields, queryAuditEvents, auditMemories, isContentWorthStoring, } from './audit.js';
+import { appendAuditEvent, reportAuditWriteFailure, auditQueryFields, queryAuditEvents, auditMemories, isContentWorthStoring, } from './audit.js';
 import { promoteToGlobal, getGlobalRoot, autoShare, searchBothHybrid } from './shared.js';
 import { writeRecallTrace, writeRecallTraceAtRoot, recordTraceOutcome } from './recall-trace.js';
 import { evalNow } from './ablation.js';
@@ -32,7 +34,7 @@ import { consolidate } from './consolidate.js';
 import { loadConfig } from './config.js';
 import { resolveProjectIdentity, classifyOriginProject, isGlobalStoreRoot } from './project-identity.js';
 import { promptTokens, contentTokens, gatePromptRecall, } from './prompt-recall.js';
-import { detectSecret } from './secret-detect.js';
+import { detectSecret, vetSecrets } from './secret-detect.js';
 import { isSessionDigestRow } from './session-digest.js';
 import { deduplicateStore } from './dedupe.js';
 import { computeAmbientState } from './ambient.js';
@@ -68,7 +70,7 @@ export function adminActor(subject) {
  *     full-store fallback (codex v1.7.0 diff-pass P1). Validated upfront
  *     so the contract holds.
  */
-export class RecallContractError extends Error {
+export class RecallContractError extends BadRequestError {
     code;
     constructor(code, message) {
         super(message);
@@ -76,13 +78,6 @@ export class RecallContractError extends Error {
         this.code = code;
     }
 }
-/** The actor's role or identity does not allow the operation. HTTP maps it to 403. */
-export class ForbiddenError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'ForbiddenError';
-    }
-}
 // v1.25.0: the recall-side scope predicates (PRIVATE_SCOPE_RE, isPrivateScope,
 // passesScopeFilterForRecall) live in recall-scope.ts (leaf) so shared.ts can
 // apply the same default-deny rule to searchBothHybrid's internal loads
@@ -170,9 +165,10 @@ export function oneCopyPerMemory(local, global, now) {
     return [local.filter((e) => kept.has(e)), global.filter((e) => kept.has(e))];
 }
 export function remember(ctx, opts) {
-    const detection = opts.untrusted ? detectInstruction(opts.content) : { flagged: false, reason: null };
+    const vetted = vetSecrets(opts.content, opts.tags ?? [], opts.untrusted === true);
+    const detection = opts.untrusted ? detectInstruction(vetted.content) : { flagged: false, reason: null };
     const requestedScope = opts.scope ?? null;
-    const entry = createMemory(opts.content, {
+    const entry = createMemory(vetted.content, {
         kind: opts.kind ?? 'distilled',
         scope: detection.flagged ? quarantineScopeFor(requestedScope) : requestedScope,
         owner: opts.owner ?? null,
@@ -199,6 +195,8 @@ export function remember(ctx, opts) {
     const result = { id: entry.id, kind: entry.kind, tenantId: ctx.tenantId };
     if (detection.flagged)
         result.quarantined = { reason: detection.reason ?? 'unknown' };
+    if (vetted.warnings.length > 0)
+        result.warnings = vetted.warnings;
     return result;
 }
 /**
@@ -1107,7 +1105,7 @@ export function forget(ctx, id) {
             .prepare(`SELECT tenant_id FROM memories WHERE id = ?`)
             .get(id);
         if (!row || row.tenant_id !== ctx.tenantId) {
-            throw new Error(`memory not found: ${id}`);
+            throw new NotFoundError(`memory not found: ${id}`);
         }
     }
     finally {
@@ -1115,7 +1113,7 @@ export function forget(ctx, id) {
     }
     const removed = deleteEntry(ctx.hippoRoot, id, { actor: ctx.actor.subject });
     if (!removed) {
-        throw new Error(`memory not found: ${id}`);
+        throw new NotFoundError(`memory not found: ${id}`);
     }
     // Counted here, not in the CLI: both callers of this function (cmdForget and
     // the HTTP route) are the two paths of one user command, so neither can miss
@@ -1150,7 +1148,7 @@ export function reject(ctx, opts) {
                 .prepare(`SELECT tenant_id FROM memories WHERE id = ?`)
                 .get(opts.memoryId);
             if (!row || row.tenant_id !== ctx.tenantId) {
-                throw new Error(`memory not found: ${opts.memoryId}`);
+                throw new NotFoundError(`memory not found: ${opts.memoryId}`);
             }
         }
         finally {
@@ -1176,10 +1174,10 @@ export function reject(ctx, opts) {
 export function unreject(ctx, digestOrPrefix) {
     const outcome = unrejectValue(ctx.hippoRoot, ctx.tenantId, digestOrPrefix, ctx.actor.subject);
     if (outcome.status === 'not_found') {
-        throw new Error(`no rejected value matches: ${digestOrPrefix}`);
+        throw new NotFoundError(`no rejected value matches: ${digestOrPrefix}`);
     }
     if (outcome.status === 'ambiguous') {
-        throw new Error(`"${digestOrPrefix}" matches ${outcome.candidates.length} tombstones; use a longer prefix`);
+        throw new BadRequestError(`"${digestOrPrefix}" matches ${outcome.candidates.length} tombstones; use a longer prefix`);
     }
     return { ok: true, digest: outcome.digest };
 }
@@ -1202,7 +1200,7 @@ export function promote(ctx, id) {
             .prepare(`SELECT tenant_id FROM memories WHERE id = ?`)
             .get(id);
         if (!row || row.tenant_id !== ctx.tenantId) {
-            throw new Error(`memory not found: ${id}`);
+            throw new NotFoundError(`memory not found: ${id}`);
         }
     }
     finally {
@@ -1234,13 +1232,13 @@ export function supersede(ctx, oldId, newContent) {
     // info leak.
     const old = readEntry(ctx.hippoRoot, oldId, ctx.tenantId);
     if (!old) {
-        throw new Error(`Memory not found: ${oldId}`);
+        throw new NotFoundError(`Memory not found: ${oldId}`);
     }
     // Guard: not already superseded. The CAS UPDATE below race-safely closes
     // the window between this read and the write; this check just produces a
     // clearer error in the common single-writer case.
     if (old.superseded_by) {
-        throw new Error(`Memory ${oldId} is already superseded by ${old.superseded_by}. Supersede that one instead.`);
+        throw new ConflictError(`Memory ${oldId} is already superseded by ${old.superseded_by}. Supersede that one instead.`);
     }
     const newEntry = createSuccessor(old, newContent, {
         tenantId: ctx.tenantId,
@@ -1268,7 +1266,7 @@ export function supersede(ctx, oldId, newContent) {
       `).run(newEntry.id, oldId, ctx.tenantId);
             if ((result.changes ?? 0) === 0) {
                 db.exec('ROLLBACK');
-                throw new Error(`Memory ${oldId} already superseded by another writer`);
+                throw new ConflictError(`Memory ${oldId} already superseded by another writer`);
             }
             // v0.30 / E2 — DAG live-coupling: OLD entry just transitioned to
             // superseded. Its parent (if any) needs rebuild. Lands strictly
@@ -1339,7 +1337,7 @@ export function archiveRaw(ctx, id, reason, opts = {}) {
             .prepare(`SELECT tenant_id FROM memories WHERE id = ?`)
             .get(id);
         if (!row || row.tenant_id !== ctx.tenantId) {
-            throw new Error(`memory not found: ${id}`);
+            throw new NotFoundError(`memory not found: ${id}`);
         }
         archiveRawMemory(db, id, {
             reason,
@@ -1418,8 +1416,9 @@ export function authCreate(ctx, opts) {
                 },
             });
         }
-        catch {
+        catch (error) {
             // Audit must not crash a successful mint.
+            reportAuditWriteFailure('auth_create', String(error), result.keyId);
         }
         return { keyId: result.keyId, plaintext: result.plaintext, tenantId: ctx.tenantId, role };
     }
@@ -1457,11 +1456,11 @@ export function authRevoke(ctx, keyId) {
             .prepare(`SELECT key_id, tenant_id, revoked_at, role FROM api_keys WHERE key_id = ?`)
             .get(keyId);
         if (!row) {
-            throw new Error(`Unknown key_id: ${keyId}`);
+            throw new NotFoundError(`Unknown key_id: ${keyId}`);
         }
         // Cross-tenant access denied: same message as missing key, no info leak.
         if (row.tenant_id !== ctx.tenantId) {
-            throw new Error(`Unknown key_id: ${keyId}`);
+            throw new NotFoundError(`Unknown key_id: ${keyId}`);
         }
         if (ctx.actor.viaAuthResolver && row.role === 'admin') {
             throw new ForbiddenError('An auth resolver admin cannot revoke an admin key, which outranks it');
@@ -1490,8 +1489,9 @@ export function authRevoke(ctx, keyId) {
                     targetId: keyId,
                 });
             }
-            catch {
+            catch (error) {
                 // Audit must not crash a successful revoke.
+                reportAuditWriteFailure('auth_revoke', String(error), keyId);
             }
         }
         return { ok: true, revokedAt };
@@ -1519,13 +1519,13 @@ function changeScopeGrant(ctx, keyId, scope, op) {
             .prepare(`SELECT tenant_id, revoked_at FROM api_keys WHERE key_id = ?`)
             .get(keyId);
         if (!row || row.tenant_id !== ctx.tenantId) {
-            throw new Error(`Unknown key_id: ${keyId}`);
+            throw new NotFoundError(`Unknown key_id: ${keyId}`);
         }
         if (op === 'auth_grant' && row.revoked_at) {
-            throw new Error(`${keyId} is revoked; a grant on it would never apply`);
+            throw new ConflictError(`${keyId} is revoked; a grant on it would never apply`);
         }
         if (!isRestrictedScope(scope)) {
-            throw new Error(`${scope} is not a restricted scope; it is already readable by default`);
+            throw new BadRequestError(`${scope} is not a restricted scope; it is already readable by default`);
         }
         if (op === 'auth_grant')
             grantScope(db, keyId, scope);
@@ -1536,7 +1536,7 @@ function changeScopeGrant(ctx, keyId, scope, op) {
         }
         catch (err) {
             // Audit must not undo a grant change that already committed; surface it instead.
-            console.error(`auth: audit write failed for ${op} ${keyId}: ${err instanceof Error ? err.message : String(err)}`);
+            reportAuditWriteFailure(op, String(err), keyId);
         }
         return { ok: true };
     }
@@ -2231,10 +2231,10 @@ export function restoreDormant(ctx, id) {
         try {
             const dormant = readDormantSnapshot(db, ctx.tenantId, id);
             if (!dormant) {
-                throw new Error(`dormant memory not found: ${id}`);
+                throw new NotFoundError(`dormant memory not found: ${id}`);
             }
             if (db.prepare(`SELECT 1 FROM memories WHERE id = ?`).get(id) !== undefined) {
-                throw new Error(`memory ${id} is already active; forget it before restoring its dormant copy`);
+                throw new ConflictError(`memory ${id} is already active; forget it before restoring its dormant copy`);
             }
             const now = new Date();
             // Dormant rows are long-lived, so a snapshot can predate a field added
@@ -2293,7 +2293,7 @@ export function forgetDormant(ctx, id) {
     const db = openHippoDb(ctx.hippoRoot);
     try {
         if (!deleteDormantRow(db, ctx.tenantId, id)) {
-            throw new Error(`dormant memory not found: ${id}`);
+            throw new NotFoundError(`dormant memory not found: ${id}`);
         }
         try {
             appendAuditEvent(db, {
@@ -2304,8 +2304,9 @@ export function forgetDormant(ctx, id) {
                 metadata: { dormant: true },
             });
         }
-        catch {
+        catch (error) {
             // Best-effort, like every other forget audit row: the delete stands.
+            reportAuditWriteFailure('forget', String(error), id);
         }
     }
     finally {
@@ -2351,9 +2352,9 @@ export function quarantineList(ctx, opts = {}) {
 function loadPendingQuarantineRow(db, tenantId, id) {
     const row = getQuarantineRow(db, tenantId, id);
     if (!row)
-        throw new Error(`not quarantined: ${id}`);
+        throw new NotFoundError(`not quarantined: ${id}`);
     if (row.status !== 'pending')
-        throw new Error(`${id} is already ${row.status}`);
+        throw new ConflictError(`${id} is already ${row.status}`);
     return row;
 }
 /** Release a quarantined memory to its original scope. Admin only; the scope guard refuses a row moved since (mirrors restoreDormant). */
@@ -2371,7 +2372,7 @@ export function quarantineApprove(ctx, id) {
                 .prepare(`UPDATE memories SET scope = ? WHERE id = ? AND tenant_id = ? AND scope = ?`)
                 .run(row.originalScope, id, ctx.tenantId, quarantineScope);
             if (Number(updated.changes ?? 0) !== 1) {
-                throw new Error(`memory ${id} scope changed since quarantine; refusing to approve`);
+                throw new ConflictError(`memory ${id} scope changed since quarantine; refusing to approve`);
             }
             approveQuarantineRow(db, ctx.tenantId, id, ctx.actor.subject);
             appendAuditEvent(db, {
@@ -2688,16 +2689,8 @@ export async function sleep(ctx, opts = {}) {
             }
         }
         catch (auditErr) {
-            // Audit emit failure must NOT mask the original phaseError. Log to
-            // stderr so the secondary failure is observable but does not throw.
-            // This guards the case where consolidation AND audit-emit fail in the
-            // same invocation against the same DB (correlated: same disk, same
-            // schema state) — losing the original error makes diagnosis much harder.
-            // SAFETY: this is a best-effort log message only; property access on
-            // any JS value is safe (undefined if absent), preserving the existing
-            // lenient formatting even when something non-Error was thrown.
-            // eslint-disable-next-line no-console
-            console.error(`[hippo] api.sleep audit emit failed: ${auditErr.message}`);
+            // Logged, never thrown: a second failure must not mask the original phaseError.
+            reportAuditWriteFailure('consolidate', String(auditErr));
         }
     }
 }

package/dist/audit.d.ts

@@ -33,6 +33,10 @@ export type AuditQueryFields = {
 };
 export declare function auditQueryFields(query: string): AuditQueryFields;
 export declare function appendAuditEvent(db: DatabaseSyncLike, opts: AppendAuditOpts): void;
+/** For callers that keep a mutation when its audit row fails: the failure is logged and counted, never silent. */
+export declare function reportAuditWriteFailure(op: AuditOp, reason: string, targetId?: string | null): void;
+/** Audit rows this process failed to write; the loopback `/health` body reports it. */
+export declare function auditWriteFailureCount(): number;
 export interface QueryAuditOpts {
     tenantId: string;
     op?: AuditOp;

package/dist/audit.js

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import { canAutoDelete } from './memory.js';
+import { log } from './log.js';
 export const STOP_WORDS = new Set([
     'the', 'a', 'an', 'is', 'was', 'are', 'were', 'be', 'been', 'being',
     'to', 'of', 'in', 'for', 'on', 'with', 'at', 'by', 'from', 'it',
@@ -250,6 +251,16 @@ export function auditQueryFields(query) {
 export function appendAuditEvent(db, opts) {
     db.prepare(`INSERT INTO audit_log (ts, tenant_id, actor, op, target_id, metadata_json) VALUES (?, ?, ?, ?, ?, ?)`).run(new Date().toISOString(), opts.tenantId, opts.actor, opts.op, opts.targetId ?? null, JSON.stringify(opts.metadata ?? {}, bigintSafeReplacer));
 }
+let auditWriteFailures = 0;
+/** For callers that keep a mutation when its audit row fails: the failure is logged and counted, never silent. */
+export function reportAuditWriteFailure(op, reason, targetId) {
+    auditWriteFailures++;
+    log.error(`audit write failed: ${reason}`, { op, target: targetId ?? undefined });
+}
+/** Audit rows this process failed to write; the loopback `/health` body reports it. */
+export function auditWriteFailureCount() {
+    return auditWriteFailures;
+}
 export function queryAuditEvents(db, opts) {
     const where = ['tenant_id = ?'];
     const params = [opts.tenantId];

package/dist/autolearn.d.ts

@@ -20,7 +20,7 @@ export declare function extractLessons(gitLog: string, customPatterns?: string[]
  * steps: this function is the write-path gate, called by each caller that
  * actually stores a lesson, not by the parser itself.
  *
- * Order is preserved in both output arrays.
+ * Order is preserved in both output arrays; both hold lessons with secret shapes redacted.
  */
 export declare function partitionLessons(lessons: string[]): {
     kept: string[];

package/dist/autolearn.js

@@ -7,14 +7,16 @@ import { createMemory, Layer, DEFAULT_HALF_LIFE_DAYS } from './memory.js';
 import { loadAllEntries } from './store.js';
 import { textOverlap } from './search.js';
 import { isContentWorthStoring } from './audit.js';
+import { redactSecretsStrict } from './secret-detect.js';
 /** A memory of a failed command, "Command '<cmd>' failed: <truncated stderr>"; no store is in reach, so `hippo watch` re-derives its half-life from the store's config. */
 export function captureError(exitCode, stderr, command, tenantId) {
     // Truncate to first 500 chars to avoid storing megabytes of build logs
-    const wasTruncated = stderr.length > 500;
-    const truncated = stderr.slice(0, 500).trim();
+    const clean = redactSecretsStrict(stderr);
+    const wasTruncated = clean.length > 500;
+    const truncated = clean.slice(0, 500).trim();
     const suffix = wasTruncated ? ' [truncated]' : '';
     // Strip leading env var assignments (KEY=val or key=val) before the actual command name
-    const safeCmd = command.replace(/^([A-Za-z_][A-Za-z0-9_]*=\S+\s+)+/, '').trim() || '(redacted)';
+    const safeCmd = redactSecretsStrict(command.replace(/^([A-Za-z_][A-Za-z0-9_]*=\S+\s+)+/, '').trim()) || '(redacted)';
     const content = `Command '${safeCmd}' failed (exit ${exitCode}): ${truncated}${suffix}`;
     // Derive a sanitized tag from the command name (first word, strip path)
     const cmdBase = safeCmd.split(/\s+/)[0].replace(/[^a-zA-Z0-9-]/g, '');
@@ -78,12 +80,12 @@ export function extractLessons(gitLog, customPatterns) {
  * steps: this function is the write-path gate, called by each caller that
  * actually stores a lesson, not by the parser itself.
  *
- * Order is preserved in both output arrays.
+ * Order is preserved in both output arrays; both hold lessons with secret shapes redacted.
  */
 export function partitionLessons(lessons) {
     const kept = [];
     const dropped = [];
-    for (const lesson of lessons) {
+    for (const lesson of lessons.map((l) => redactSecretsStrict(l))) {
         if (isContentWorthStoring(lesson)) {
             kept.push(lesson);
         }

package/dist/capture-contract.d.ts

@@ -0,0 +1,47 @@
+/** A host lifecycle moment hippo can capture from. */
+export type CaptureEvent = 'prompt' | 'tool-failure' | 'pre-compact' | 'post-compact' | 'session-start' | 'session-end' | 'reset';
+/** What hippo read from one host payload, before anything is written. */
+export interface CaptureInput {
+    readonly runtime: string;
+    readonly event: CaptureEvent;
+    /** True when no host payload arrived: a person ran the verb by hand. */
+    readonly manual: boolean;
+    readonly sessionId: string | null;
+    readonly cwd: string | null;
+    readonly transcriptPath: string | null;
+    /** The host's own reason for the event, such as `auto` or `manual` compaction. */
+    readonly trigger: string | null;
+}
+/** The outcome of reading a payload: usable input, a payload hippo refuses, or no payload at all. */
+export type CaptureReceipt = {
+    readonly status: 'received';
+    readonly input: CaptureInput;
+} | {
+    readonly status: 'skipped' | 'unavailable';
+    readonly reason: string;
+};
+/** Working state saved before the host drops context, so the session can resume; it is not a lesson. */
+export interface Checkpoint {
+    readonly runtime: string;
+    readonly sessionId: string | null;
+    readonly task: string;
+    readonly summary: string;
+    readonly nextStep: string;
+    readonly savedAt: string;
+}
+/** How far capture has read one session's source, so a retry resumes instead of re-reading or skipping. */
+export interface ProgressCursor {
+    readonly runtime: string;
+    readonly sessionId: string;
+    readonly source: string;
+    /** Opaque position in the source, such as a byte offset or the last turn id read. */
+    readonly position: string;
+    readonly updatedAt: string;
+}
+/** A string guard that avoids `typeof`; it matches it for every value `JSON.parse` can produce. */
+export declare function isStringValue<T>(value: T): value is T & string;
+/** An object guard that avoids `typeof`; arrays count as objects, as they do for `typeof`. */
+export declare function isObjectLike<T>(value: T): value is T & object;
+/** Reads a Claude Code PreCompact payload; only an empty stdin counts as a manual run. */
+export declare function readClaudeCodePreCompact(stdinText: string | undefined, timedOut: boolean): CaptureReceipt;
+//# sourceMappingURL=capture-contract.d.ts.map

package/dist/capture-contract.js

@@ -0,0 +1,49 @@
+// The shared shape every agent adapter turns a host payload into, so capture code is written once for all runtimes.
+// Field meanings, statuses and how to add a runtime: docs/integrations/agent-inventory.md.
+/** A string guard that avoids `typeof`; it matches it for every value `JSON.parse` can produce. */
+export function isStringValue(value) {
+    return String(value) === value;
+}
+/** An object guard that avoids `typeof`; arrays count as objects, as they do for `typeof`. */
+export function isObjectLike(value) {
+    return value !== null && value instanceof Object;
+}
+/** Reads a Claude Code PreCompact payload; only an empty stdin counts as a manual run. */
+export function readClaudeCodePreCompact(stdinText, timedOut) {
+    const empty = !stdinText || stdinText.trim() === '';
+    if (timedOut && empty) {
+        return { status: 'unavailable', reason: 'no PreCompact payload arrived before the stdin wait window closed' };
+    }
+    const base = { runtime: 'claude-code', event: 'pre-compact' };
+    if (empty) {
+        return { status: 'received', input: { ...base, manual: true, sessionId: null, cwd: null, transcriptPath: null, trigger: null } };
+    }
+    let payload;
+    try {
+        payload = JSON.parse(stdinText.trim());
+    }
+    catch {
+        // Non-JSON stdin leaves payload undefined, which the shape check rejects like an explicit null.
+    }
+    // A bad payload is skipped, never treated as manual: discovery could pick up another session's transcript.
+    if (!isObjectLike(payload) || !('transcript_path' in payload) || !isStringValue(payload.transcript_path)) {
+        return { status: 'skipped', reason: 'malformed or incomplete PreCompact payload (missing string transcript_path)' };
+    }
+    const transcriptPath = payload.transcript_path;
+    // Path shape only: CLAUDE_CONFIG_DIR can move the transcript root, and a same-user process can already read every transcript.
+    if (!/\.jsonl$/i.test(transcriptPath)) {
+        return { status: 'skipped', reason: `payload transcript_path is not a .jsonl file: ${transcriptPath}` };
+    }
+    return {
+        status: 'received',
+        input: {
+            ...base,
+            manual: false,
+            sessionId: 'session_id' in payload && isStringValue(payload.session_id) ? payload.session_id : null,
+            cwd: 'cwd' in payload && isStringValue(payload.cwd) ? payload.cwd : null,
+            transcriptPath,
+            trigger: 'trigger' in payload && isStringValue(payload.trigger) ? payload.trigger : null,
+        },
+    };
+}
+//# sourceMappingURL=capture-contract.js.map

package/dist/capture-error.js

@@ -7,6 +7,7 @@ import { loadConfig } from './config.js';
 import { closeHippoDb, openHippoDb } from './db.js';
 import { recordFailure } from './failure-log.js';
 import { blockHash } from './token-ledger.js';
+import { redactSecretsStrict } from './secret-detect.js';
 const MAX_LEN = 200;
 /** The user, a permission prompt or a hook said no: routine, not a lesson. */
 const DECLINED = /user (?:doesn't|does not) want|denied by (?:the )?user|user (?:rejected|declined|denied)|permission to use|was blocked by (?:a )?hook/i;
@@ -44,7 +45,7 @@ export function lessonFromFailure(payload) {
     if (!isString(p.error) || p.error.trim().length < 12)
         return { skip: 'skipped-invalid', text: null, detail: null };
     const tool = isString(p.tool_name) ? p.tool_name : 'tool';
-    const error = p.error.replace(/\s+/g, ' ').trim();
+    const error = redactSecretsStrict(p.error.replace(/\s+/g, ' ').trim());
     const text = `${tool}: ${error}`.slice(0, MAX_LEN);
     const command = isObject(p.tool_input) && isString(p.tool_input['command']) ? p.tool_input['command'].replace(LEADING_CD, '') : '';
     const head = command.trim().split(/\s+/).slice(0, 2).join(' ');

package/dist/capture.d.ts

@@ -49,19 +49,6 @@ export interface CaptureOptions {
     tenantId?: string;
     originProject?: string;
 }
-/**
- * Runtime shape guards used throughout this file wherever a value arrives
- * unparsed (JSONL transcript records, stdout/stderr write() chunks). Generic
- * over the input so the parameter is never annotated `unknown` directly — TS
- * infers it from the call site — while the check itself avoids `typeof` by
- * testing identity against the coercion (`String(x) === x`) /
- * prototype-chain (`instanceof Object`) instead. Behaviourally equivalent to
- * `typeof x === 'string'` / a truthy `typeof x === 'object'` check for
- * anything `JSON.parse` can produce (the only divergence is boxed
- * primitives, which JSON.parse never yields).
- */
-export declare function isStringValue<T>(value: T): value is T & string;
-export declare function isObjectLike<T>(value: T): value is T & object;
 /** Message for a caught value of unknown shape. `cause` names the sanctioned unknown-input case (error-cause enrichment). */
 export declare function errorMessage(cause: unknown): string;
 /** Transcript-line flags isNonHumanUserLine reads (any may be absent); `promptSource: 'system'` marks Claude Code's own notices. */