hippo-memory 1.56.0 → 1.58.0

package/dist/recall-scope.d.ts

@@ -6,6 +6,29 @@
  * these for its own call sites AND re-exports them for back-compat
  * (`api.isPrivateScope`, test imports of `passesScopeFilterForRecall`).
  */
+import { ForbiddenError } from './api-errors.js';
+/**
+ * Literal scopes excluded from recall by default-deny when the
+ * caller passes no `scope`. The SQL clause in `loadSearchRows` and the JS
+ * helper `passesScopeFilterForRecall` (src/api.ts) both read from this
+ * constant. Adding a deny scope is a one-place change.
+ *
+ * Regex-based denies (e.g. `<source>:private:*`) stay in
+ * `passesScopeFilterForRecall` as a separate JS step — they don't translate
+ * cleanly to SQL.
+ *
+ * Invariant: never empty. An empty array would silently allow quarantine
+ * scopes through both paths (SQL clause omitted, JS check vacuous). The
+ * module-load assertion below pins this loudly.
+ */
+export declare const RECALL_DEFAULT_DENY_SCOPES: readonly ["unknown:legacy"];
+/**
+ * @internal Runtime guard against a future maintainer blanking a
+ * load-bearing literal array. Extracted from the inline guard so the throw
+ * path is directly testable. `as const` arrays widen via `readonly T[]` at
+ * the call site so the empty case is reachable at runtime.
+ */
+export declare function assertNonEmpty<T>(arr: readonly T[], name: string): void;
 /**
  * v1.2.1: source-agnostic private-scope detector. A scope string is treated
  * as private when it has the shape `<lowercase-source>:private:<rest>`.
@@ -61,7 +84,7 @@ export declare function passesCliRecallScopeFilter(scope: string | null, request
  * Thrown when a caller requests a scope its role may not read. The HTTP layer
  * maps it to 403.
  */
-export declare class ScopeForbiddenError extends Error {
+export declare class ScopeForbiddenError extends ForbiddenError {
     readonly scope: string;
     constructor(scope: string);
 }

package/dist/recall-scope.js

@@ -6,7 +6,34 @@
  * these for its own call sites AND re-exports them for back-compat
  * (`api.isPrivateScope`, test imports of `passesScopeFilterForRecall`).
  */
-import { RECALL_DEFAULT_DENY_SCOPES } from './store.js';
+import { ForbiddenError } from './api-errors.js';
+/**
+ * Literal scopes excluded from recall by default-deny when the
+ * caller passes no `scope`. The SQL clause in `loadSearchRows` and the JS
+ * helper `passesScopeFilterForRecall` (src/api.ts) both read from this
+ * constant. Adding a deny scope is a one-place change.
+ *
+ * Regex-based denies (e.g. `<source>:private:*`) stay in
+ * `passesScopeFilterForRecall` as a separate JS step — they don't translate
+ * cleanly to SQL.
+ *
+ * Invariant: never empty. An empty array would silently allow quarantine
+ * scopes through both paths (SQL clause omitted, JS check vacuous). The
+ * module-load assertion below pins this loudly.
+ */
+export const RECALL_DEFAULT_DENY_SCOPES = ['unknown:legacy'];
+/**
+ * @internal Runtime guard against a future maintainer blanking a
+ * load-bearing literal array. Extracted from the inline guard so the throw
+ * path is directly testable. `as const` arrays widen via `readonly T[]` at
+ * the call site so the empty case is reachable at runtime.
+ */
+export function assertNonEmpty(arr, name) {
+    if (arr.length === 0) {
+        throw new Error(`${name} cannot be empty — would silently allow quarantine scopes`);
+    }
+}
+assertNonEmpty(RECALL_DEFAULT_DENY_SCOPES, 'RECALL_DEFAULT_DENY_SCOPES');
 /**
  * v1.2.1: source-agnostic private-scope detector. A scope string is treated
  * as private when it has the shape `<lowercase-source>:private:<rest>`.
@@ -79,7 +106,7 @@ export function passesCliRecallScopeFilter(scope, requested) {
  * Thrown when a caller requests a scope its role may not read. The HTTP layer
  * maps it to 403.
  */
-export class ScopeForbiddenError extends Error {
+export class ScopeForbiddenError extends ForbiddenError {
     scope;
     constructor(scope) {
         super(`scope ${scope} requires admin role`);

package/dist/refine-llm.js

@@ -15,6 +15,7 @@
 import { Layer } from './memory.js';
 import { loadAllEntries, readEntry, writeEntry } from './store.js';
 import { redactSecrets } from './secret-detect.js';
+import { fetchWithRetry, llmTimeoutMs } from './http-retry.js';
 const REFINED_TAG = 'llm-refined';
 const CONSOLIDATED_MARKERS = [
     '[Consolidated from',
@@ -48,7 +49,7 @@ Source memories (up to 8 shown):
 ${sourceBlock}`;
     let res;
     try {
-        res = await fetchFn('https://api.anthropic.com/v1/messages', {
+        res = await fetchWithRetry('https://api.anthropic.com/v1/messages', {
             method: 'POST',
             headers: {
                 'content-type': 'application/json',
@@ -60,7 +61,7 @@ ${sourceBlock}`;
                 max_tokens: 800,
                 messages: [{ role: 'user', content: prompt }],
             }),
-        });
+        }, { timeoutMs: llmTimeoutMs(), fetchFn });
     }
     catch {
         return null;

package/dist/reject-flow.js

@@ -12,7 +12,7 @@
  * cli.ts and api.ts, so it introduces no cycle.
  */
 import { closeHippoDb } from './db.js';
-import { appendAuditEvent } from './audit.js';
+import { appendAuditEvent, reportAuditWriteFailure } from './audit.js';
 import { archiveRawMemory } from './raw-archive.js';
 import { deleteDormantRow, listDormantSnapshots, purgeDormantByDigest, replaceDormantEntry } from './dormant.js';
 import { openStore, deleteEntryCore, purgeMirrorBestEffort, selectAllEntries, stampOriginProject, writeEntryDbOnly, writeEntryMirrors, } from './store.js';
@@ -144,12 +144,9 @@ export function rejectValue(opts) {
                     metadata: { digest, removedIds, count: removedIds.length },
                 });
             }
-            catch {
-                // Best-effort — mirrors store.ts's private audit() semantics. This
-                // runs INSIDE the still-open transaction (COMMIT is the next
-                // statement): a swallowed audit failure lets the tombstone +
-                // removals commit without the trail row, rather than rolling the
-                // whole reject back over bookkeeping.
+            catch (error) {
+                // Inside the open transaction: the reject commits without its trail row rather than rolling back over bookkeeping.
+                reportAuditWriteFailure('reject_value', String(error), opts.memoryId);
             }
             db.exec('COMMIT');
         }
@@ -217,8 +214,8 @@ export function unrejectValue(hippoRoot, tenantId, digestOrPrefix, actor) {
                 metadata: { digest: target.digest, reason: target.reason },
             });
         }
-        catch {
-            // Best-effort, same as reject's audit call above.
+        catch (error) {
+            reportAuditWriteFailure('unreject_value', String(error), target.sourceMemoryId);
         }
         return { status: 'ok', digest: target.digest, reason: target.reason };
     }

package/dist/rejection.d.ts

@@ -12,6 +12,7 @@
  * be a cycle.
  */
 import type { DatabaseSyncLike } from './db.js';
+import { BadRequestError } from './api-errors.js';
 /**
  * Normalize content for rejection-digest comparisons: Unicode NFC →
  * lowercase → collapse whitespace runs to a single space → trim. No
@@ -33,7 +34,7 @@ export declare function rejectionDigest(content: string): string;
  * blocks (writeEntry, api.supersede) to write a post-rollback
  * `reject_refusal` audit row via `auditRejectionRefusal` (plan §3).
  */
-export declare class RejectedValueError extends Error {
+export declare class RejectedValueError extends BadRequestError {
     readonly digest: string;
     readonly tenantId: string;
     readonly entryId: string;

package/dist/rejection.js

@@ -12,6 +12,7 @@
  * be a cycle.
  */
 import { createHash } from 'node:crypto';
+import { BadRequestError } from './api-errors.js';
 /**
  * Normalize content for rejection-digest comparisons: Unicode NFC →
  * lowercase → collapse whitespace runs to a single space → trim. No
@@ -37,7 +38,7 @@ export function rejectionDigest(content) {
  * blocks (writeEntry, api.supersede) to write a post-rollback
  * `reject_refusal` audit row via `auditRejectionRefusal` (plan §3).
  */
-export class RejectedValueError extends Error {
+export class RejectedValueError extends BadRequestError {
     digest;
     tenantId;
     entryId;

package/dist/search.d.ts

@@ -7,7 +7,6 @@ import { MemoryEntry } from './memory.js';
 import type { PhysicsConfig } from './physics-config.js';
 export declare const CHURN_STALE_RANK_MULTIPLIER = 0.5;
 export declare function churnStaleFactor(entry: MemoryEntry): number;
-export declare function tokenize(text: string): string[];
 /**
  * Tokenized BM25 corpus. Callers can pre-build this with `buildCorpus` once
  * and reuse across many `hybridSearch` calls on the same entry set — the
@@ -287,25 +286,6 @@ export declare function search(query: string, entries: MemoryEntry[], options?:
     includeSuperseded?: boolean;
     asOf?: string;
 }): SearchResult[];
-/**
- * Update retrieval metadata on entries that were returned by a search.
- * Returns the mutated copies (caller must persist to disk).
- *
- * EVAL-ONLY ablation (see ablation.ts): with HIPPO_ABLATE_RECALL_BOOST set,
- * this returns the entries UNMUTATED - neutralizing all three strengthening
- * sub-effects (clock reset, retrieval_count, half-life increment) at the
- * single shared write site. The entries (not an empty array) must be
- * returned because callers derive `last_retrieval_ids` from the return
- * value, and a later `hippo outcome --good/--bad` targets those ids - an
- * empty return would silently co-ablate the outcome channel in the
- * strengthen-off arm (codex round-7 P2). PERSISTENCE is gated separately at
- * each persisting caller (CLI recall, api context, MCP recall/context,
- * consolidation replay): writeEntry on identical rows still refreshes
- * updated_at, rewrites mirrors, and marks DAG parents dirty (codex round-6
- * P2), so those write loops skip under the flag.
- * The default `now` honors HIPPO_FAKE_NOW (simulated-time protocols).
- */
-export declare function markRetrieved(entries: MemoryEntry[], now?: Date): MemoryEntry[];
 export interface MatchExplanation {
     /** Human-readable reason string */
     reason: string;

package/dist/search.js

@@ -3,7 +3,8 @@
  * Zero external dependencies when embeddings are not available.
  */
 import { estimateTokens } from './token-ledger.js';
-import { calculateStrength, netWrong, CHURN_STALE_TAG } from './memory.js';
+import { calculateStrength, CHURN_STALE_TAG } from './memory.js';
+import { tokenize } from './tokenize.js';
 import { isOutcomeFastAblated, isRecallBoostAblated, isRecencyAblated, evalRecencyScaleDays, evalNow } from './ablation.js';
 import { extractPathTags, pathBoostMultiplier } from './path-context.js';
 import { detectScope, scopeMatch } from './scope.js';
@@ -16,20 +17,16 @@ import { openHippoDb, closeHippoDb } from './db.js';
 import { rrfFuse } from './rrf.js';
 import { graphRankStream, selectGraphSeeds, DEFAULT_GRAPH_SEED_COUNT } from './graph-stream.js';
 import { compareEntryIdentity, compareScoredResults } from './compare.js';
+import { log } from './log.js';
+import { redactSecretsStrict } from './secret-detect.js';
 export const CHURN_STALE_RANK_MULTIPLIER = 0.5; // SHORTCUT: untuned; FE3 measures before any default.
+// Search runs on every hook prompt, so one line per reason per process says why vectors went unused without flooding stderr.
+function warnBm25Fallback(reason, detail) {
+    log.once(`search.bm25-fallback.${reason}`, 'warn', `hybrid search fell back to BM25 only: ${redactSecretsStrict(detail)}`);
+}
 export function churnStaleFactor(entry) {
     return entry.tags.includes(CHURN_STALE_TAG) ? CHURN_STALE_RANK_MULTIPLIER : 1.0;
 }
-// ---------------------------------------------------------------------------
-// Tokenizer
-// ---------------------------------------------------------------------------
-export function tokenize(text) {
-    return text
-        .toLowerCase()
-        .replace(/[^\w\s]/g, ' ')
-        .split(/\s+/)
-        .filter((t) => t.length > 1);
-}
 const BM25_K1 = 1.5;
 const BM25_B = 0.75;
 export function buildCorpus(texts) {
@@ -276,11 +273,17 @@ export async function hybridSearch(query, entries, options = {}) {
                         embeddingIndex = idx;
                         useEmbeddings = true;
                     }
+                    else {
+                        warnBm25Fallback('empty-query-vector', 'the embedding provider returned no vector for the query');
+                    }
                 }
             }
+            else if (provider.isAvailable()) {
+                warnBm25Fallback('reindex', "the embedding index was built by another model or is being rebuilt; run 'hippo embed'");
+            }
         }
-        catch {
-            // Fall through to BM25-only
+        catch (err) {
+            warnBm25Fallback('error', err instanceof Error ? err.message : String(err));
         }
     }
     // Compute cosine similarities for RRF ranking (need all before scoring)
@@ -902,44 +905,6 @@ export function search(query, entries, options = {}) {
     }
     return fitBudget(dedupedSync, budget, minResults, options.cost);
 }
-/**
- * Update retrieval metadata on entries that were returned by a search.
- * Returns the mutated copies (caller must persist to disk).
- *
- * EVAL-ONLY ablation (see ablation.ts): with HIPPO_ABLATE_RECALL_BOOST set,
- * this returns the entries UNMUTATED - neutralizing all three strengthening
- * sub-effects (clock reset, retrieval_count, half-life increment) at the
- * single shared write site. The entries (not an empty array) must be
- * returned because callers derive `last_retrieval_ids` from the return
- * value, and a later `hippo outcome --good/--bad` targets those ids - an
- * empty return would silently co-ablate the outcome channel in the
- * strengthen-off arm (codex round-7 P2). PERSISTENCE is gated separately at
- * each persisting caller (CLI recall, api context, MCP recall/context,
- * consolidation replay): writeEntry on identical rows still refreshes
- * updated_at, rewrites mirrors, and marks DAG parents dirty (codex round-6
- * P2), so those write loops skip under the flag.
- * The default `now` honors HIPPO_FAKE_NOW (simulated-time protocols).
- */
-// Confidence is deliberately absent below: it is an epistemic tier, not a
-// recency signal, and a stored 'stale' is always a deliberate mark (2026-09-07).
-export function markRetrieved(entries, now = evalNow()) {
-    if (isRecallBoostAblated())
-        return entries;
-    return entries.map((e) => {
-        if (e.superseded_by)
-            return e;
-        const wrong = netWrong(e) > 0;
-        const updated = {
-            ...e,
-            retrieval_count: e.retrieval_count + 1,
-            last_retrieved: wrong ? e.last_retrieved : now.toISOString(),
-            // +2 days half-life per retrieval (PLAN.md); a wrong memory keeps both, since last_retrieved is the decay anchor
-            half_life_days: wrong ? e.half_life_days : e.half_life_days + 2,
-        };
-        updated.strength = calculateStrength(updated, now);
-        return updated;
-    });
-}
 /**
  * Explain why a search result matched a query.
  * Computes which query terms overlapped with the document and whether

package/dist/secret-detect.d.ts

@@ -12,7 +12,8 @@
  *    a deliberate act.
  *
  * This is deliberately a thin slice of the A4 lifecycle-compliance item
- * (no write-time scrubbing, no PII detection).
+ * (no PII detection). Write-time scrubbing covers only text no person
+ * typed into hippo; see `vetSecrets`.
  *
  * Leaf module: keep free of imports from store/api/shared so all of them
  * can import it without cycles.
@@ -42,4 +43,15 @@ export declare function redactSecrets(text: string): string;
 export declare function maskEmails(text: string): string;
 /** Stricter redaction for text that leaves the machine: no co-occurrence guard, plus Bearer and Basic auth headers and JWTs. */
 export declare function redactSecretsStrict(text: string): string;
+/** The text a write keeps, plus what to tell its caller about secret material in it. */
+export interface SecretVet {
+    content: string;
+    warnings: string[];
+}
+/** Write-time veto: `scrub` text no person typed gets capture's strict redaction; typed text is a person's own call, so it is kept and flagged. */
+export declare function vetSecrets(content: string, tags: readonly string[], scrub: boolean): SecretVet;
+/** Appended to a dead-letter row's error when `redactPayload` changed its body. */
+export declare const DLQ_REDACTED_NOTE = "secret-shaped text redacted, signature dropped; replay needs --force";
+/** `vetSecrets` redaction for a raw webhook body: JSON stays valid for replay, and an untouched body stays byte-identical so its signature still verifies. */
+export declare function redactPayload(raw: string): string;
 //# sourceMappingURL=secret-detect.d.ts.map

package/dist/secret-detect.js

@@ -12,7 +12,8 @@
  *    a deliberate act.
  *
  * This is deliberately a thin slice of the A4 lifecycle-compliance item
- * (no write-time scrubbing, no PII detection).
+ * (no PII detection). Write-time scrubbing covers only text no person
+ * typed into hippo; see `vetSecrets`.
  *
  * Leaf module: keep free of imports from store/api/shared so all of them
  * can import it without cycles.
@@ -100,6 +101,37 @@ export function maskEmails(text) {
 export function redactSecretsStrict(text) {
     return redactText(text, true);
 }
+/** Write-time veto: `scrub` text no person typed gets capture's strict redaction; typed text is a person's own call, so it is kept and flagged. */
+export function vetSecrets(content, tags, scrub) {
+    const kept = scrub ? redactSecretsStrict(content) : content;
+    const warnings = [];
+    if (kept !== content) {
+        const found = detectSecret({ content, tags: [] }).reason;
+        warnings.push(`secret-shaped text was redacted before storing${found ? ` (${found})` : ''}`);
+    }
+    const left = detectSecret({ content: kept, tags: [...tags] });
+    if (left.flagged) {
+        warnings.push(`content looks like a secret (${left.reason}) and was stored as sent; forget it if it should not be kept`);
+    }
+    return { content: kept, warnings };
+}
+const JSON_STRING = /"(?:[^"\\]|\\.)*"/g;
+/** Appended to a dead-letter row's error when `redactPayload` changed its body. */
+export const DLQ_REDACTED_NOTE = 'secret-shaped text redacted, signature dropped; replay needs --force';
+/** `vetSecrets` redaction for a raw webhook body: JSON stays valid for replay, and an untouched body stays byte-identical so its signature still verifies. */
+export function redactPayload(raw) {
+    try {
+        JSON.parse(raw);
+    }
+    catch {
+        return redactSecretsStrict(raw);
+    }
+    return raw.replace(JSON_STRING, (literal) => {
+        const text = JSON.parse(literal);
+        const kept = redactSecretsStrict(text);
+        return kept === text ? literal : JSON.stringify(kept);
+    });
+}
 function redactText(text, strict) {
     if (!text)
         return text;

package/dist/server.d.ts

@@ -66,7 +66,9 @@ export declare function clientIpForRateLimit(req: IncomingMessage): string;
  * webhooks in PUBLIC_ROUTES, which are HMAC-gated by their own signing
  * secrets and 404 when those secrets are unset. But the loopback
  * no-auth fallback inside buildContextWithAuth still admits unauthenticated
- * requests from a loopback remote address, so binding to a non-loopback host
+ * requests from a loopback remote address (unless they carry Forwarded,
+ * X-Forwarded-For/-Host/-Proto, X-Real-IP, Cf-Connecting-Ip or True-Client-Ip, which mark a same-host proxy and get
+ * a 401 like any keyless remote request), so binding to a non-loopback host
  * is only safe once that fallback is disabled with HIPPO_REQUIRE_AUTH=1,
  * which forces every request (loopback or not) through Bearer-token
  * validation. Without that env var set, a non-loopback bind would expose the