hippo-memory 1.57.0 → 1.59.0

package/dist/db.d.ts

@@ -10,6 +10,8 @@ export interface DatabaseSyncLike {
     exec(sql: string): void;
     prepare(sql: string): StatementSyncLike;
     close(): void;
+    readonly isOpen?: boolean;
+    readonly isTransaction?: boolean;
 }
 export declare function getHippoDbPath(hippoRoot: string): string;
 export declare function getCurrentSchemaVersion(): number;
@@ -17,6 +19,16 @@ export declare function getCurrentSchemaVersion(): number;
 export declare class IncompatibleBinaryError extends Error {
 }
 export declare function isSqliteBusy(error: unknown): boolean;
+export declare function execWithBusyRetry(db: DatabaseSyncLike, sql: string, timeoutMs?: number): void;
+/** Lock wait for hook commands: under the 5 s prompt-hook budget even after a few skipped writes, and far above a normal write's hold. */
+export declare const HOOK_DB_WAIT_MS = 1000;
+/** A busy store made a command skip work: warn once per process (the holder is usually `hippo sleep`). */
+export declare function noteStoreBusy(skipped: string): void;
+/** Runs `fn` with one handle per store: openHippoDb reuses it and closeHippoDb leaves it open until `fn` settles or the process exits.
+ *  `busyWaitMs` is the lock wait of every open inside `fn` that does not pass its own. */
+export declare function withSharedStoreHandles<T>(fn: () => T | Promise<T>, opts?: {
+    busyWaitMs?: number;
+}): Promise<T>;
 /** `busyWaitMs` shortens every lock wait of this open, for a hook that must finish inside its own timeout. */
 export declare function openHippoDb(hippoRoot: string, opts?: {
     busyWaitMs?: number;

package/dist/db.js

@@ -6,6 +6,7 @@ import { createPhysicsTable } from './physics-state.js';
 import { cleanupArchivedMirrors } from './raw-archive-mirror-cleanup.js';
 import { PACKAGE_VERSION, compareSemver } from './version.js';
 import { deriveOriginProject, originFromSource, isGlobalStoreRoot } from './project-identity.js';
+import { log } from './log.js';
 const require = createRequire(import.meta.url);
 // SAFETY: node:sqlite's DatabaseSync constructor genuinely has this shape at
 // runtime (Node's built-in synchronous SQLite module); there are no bundled
@@ -2607,7 +2608,7 @@ export function isSqliteBusy(error) {
 // busy_timeout covers neither of this file's two contended statements: SQLite
 // skips the busy handler for `PRAGMA journal_mode` and for a write that upgrades
 // a deferred read snapshot. Both need an explicit wait instead.
-function execWithBusyRetry(db, sql, timeoutMs = 30000) {
+export function execWithBusyRetry(db, sql, timeoutMs = 30000) {
     const deadline = Date.now() + timeoutMs;
     const idle = new Int32Array(new SharedArrayBuffer(4));
     for (;;) {
@@ -2622,8 +2623,66 @@ function execWithBusyRetry(db, sql, timeoutMs = 30000) {
         }
     }
 }
+// Hook commands run on every prompt, so inside withSharedStoreHandles each store pays its pragmas, migration check and mirror cleanup once.
+const sharedHandles = new Map();
+const sharedSet = new WeakSet();
+let shareDepth = 0;
+let shareBusyWaitMs;
+/** Lock wait for hook commands: under the 5 s prompt-hook budget even after a few skipped writes, and far above a normal write's hold. */
+export const HOOK_DB_WAIT_MS = 1000;
+/** A busy store made a command skip work: warn once per process (the holder is usually `hippo sleep`). */
+export function noteStoreBusy(skipped) {
+    log.once('store-busy', 'warn', `store busy (another hippo process holds the write lock); ${skipped}`);
+    // A lock held past one full wait belongs to a long transaction, so the hook's later writes skip at once.
+    for (const db of sharedHandles.values()) {
+        if (db.isOpen !== false)
+            db.exec('PRAGMA busy_timeout = 0');
+    }
+}
+function closeSharedStoreHandles() {
+    for (const db of sharedHandles.values()) {
+        sharedSet.delete(db);
+        if (db.isOpen !== false)
+            db.close();
+    }
+    sharedHandles.clear();
+}
+/** Runs `fn` with one handle per store: openHippoDb reuses it and closeHippoDb leaves it open until `fn` settles or the process exits.
+ *  `busyWaitMs` is the lock wait of every open inside `fn` that does not pass its own. */
+export async function withSharedStoreHandles(fn, opts) {
+    if (shareDepth++ === 0) {
+        process.once('exit', closeSharedStoreHandles);
+        shareBusyWaitMs = opts?.busyWaitMs;
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        if (--shareDepth === 0) {
+            process.off('exit', closeSharedStoreHandles);
+            closeSharedStoreHandles();
+            shareBusyWaitMs = undefined;
+        }
+    }
+}
 /** `busyWaitMs` shortens every lock wait of this open, for a hook that must finish inside its own timeout. */
 export function openHippoDb(hippoRoot, opts) {
+    if (shareDepth === 0)
+        return openOwnHippoDb(hippoRoot, opts);
+    const busyWaitMs = opts?.busyWaitMs ?? shareBusyWaitMs;
+    const key = `${path.resolve(getHippoDbPath(hippoRoot))}\0${busyWaitMs ?? ''}`;
+    const shared = sharedHandles.get(key);
+    if (shared?.isOpen && !shared.isTransaction)
+        return shared;
+    const db = openOwnHippoDb(hippoRoot, { busyWaitMs });
+    // An open nested inside a transaction gets its own connection, as it did before sharing.
+    if (!shared?.isOpen) {
+        sharedHandles.set(key, db);
+        sharedSet.add(db);
+    }
+    return db;
+}
+function openOwnHippoDb(hippoRoot, opts) {
     fs.mkdirSync(hippoRoot, { recursive: true });
     const db = new DatabaseSync(getHippoDbPath(hippoRoot));
     const busyWaitMs = opts?.busyWaitMs;
@@ -2937,6 +2996,8 @@ function backfillFtsIndex(db) {
   `);
 }
 export function closeHippoDb(db) {
+    if (sharedSet.has(db))
+        return;
     db.close();
 }
 export function getMeta(db, key, fallback = '') {

package/dist/decisions.js

@@ -23,6 +23,7 @@
  * 'write_entry' (store.ts:1196) via the afterWrite hook, so a failure in any
  * step rolls all of them back. Pattern matches savePrediction (predictions.ts).
  */
+import { BadRequestError, ConflictError, NotFoundError } from './api-errors.js';
 import { openHippoDb, closeHippoDb } from './db.js';
 import { writeEntry } from './store.js';
 import { assertTenantId } from './tenant.js';
@@ -73,7 +74,7 @@ const DECISION_COLS = `
 export function saveDecision(hippoRoot, tenantId, opts, actor = 'cli') {
     assertTenantId('saveDecision', tenantId);
     if (!opts.decisionText)
-        throw new Error('saveDecision: decisionText is required');
+        throw new BadRequestError('saveDecision: decisionText is required');
     const now = new Date().toISOString();
     const content = opts.context
         ? `${opts.decisionText}\n\nContext: ${opts.context}`
@@ -103,10 +104,10 @@ export function saveDecision(hippoRoot, tenantId, opts, actor = 'cli') {
                 // SAFETY: row shape matches the single `status` column named in the SELECT below.
                 const pred = db.prepare(`SELECT status FROM decisions WHERE id = ? AND tenant_id = ?`).get(opts.supersedesDecisionId, tenantId);
                 if (!pred) {
-                    throw new Error(`saveDecision: decision ${opts.supersedesDecisionId} to supersede not found for tenant ${tenantId}`);
+                    throw new NotFoundError(`saveDecision: decision ${opts.supersedesDecisionId} to supersede not found for tenant ${tenantId}`);
                 }
                 if (pred.status !== 'active') {
-                    throw new Error(`saveDecision: decision ${opts.supersedesDecisionId} is not active (status='${pred.status}'); only active decisions can be superseded.`);
+                    throw new ConflictError(`saveDecision: decision ${opts.supersedesDecisionId} is not active (status='${pred.status}'); only active decisions can be superseded.`);
                 }
             }
             const result = db.prepare(`
@@ -127,7 +128,7 @@ export function saveDecision(hippoRoot, tenantId, opts, actor = 'cli') {
           WHERE id = ? AND tenant_id = ? AND status = 'active' AND id != ?
         `).run(decisionId, now, opts.supersedesDecisionId, tenantId, decisionId);
                 if (sup.changes === 0) {
-                    throw new Error(`saveDecision: decision ${opts.supersedesDecisionId} could not be superseded (no longer active or self-reference).`);
+                    throw new BadRequestError(`saveDecision: decision ${opts.supersedesDecisionId} could not be superseded (no longer active or self-reference).`);
                 }
                 appendAuditEvent(db, {
                     tenantId,
@@ -191,15 +192,15 @@ export function closeDecision(hippoRoot, tenantId, id, actor = 'cli') {
                 // SAFETY: row shape matches the single `status` column named in the SELECT above.
                 const existing = db.prepare(`SELECT status FROM decisions WHERE id = ? AND tenant_id = ?`).get(id, tenantId);
                 if (!existing) {
-                    throw new Error(`closeDecision: decision ${id} not found for tenant ${tenantId}`);
+                    throw new NotFoundError(`closeDecision: decision ${id} not found for tenant ${tenantId}`);
                 }
-                throw new Error(`closeDecision: decision ${id} is not active (status='${existing.status}'); only active decisions can be closed.`);
+                throw new ConflictError(`closeDecision: decision ${id} is not active (status='${existing.status}'); only active decisions can be closed.`);
             }
             // SAFETY: row's shape matches the columns named in DECISION_COLS above.
             const row = db.prepare(`SELECT ${DECISION_COLS} FROM decisions WHERE id = ? AND tenant_id = ?`)
                 .get(id, tenantId);
             if (!row)
-                throw new Error(`closeDecision: decision ${id} not found after UPDATE`);
+                throw new NotFoundError(`closeDecision: decision ${id} not found after UPDATE`);
             appendAuditEvent(db, {
                 tenantId,
                 actor,
@@ -256,7 +257,7 @@ export function loadDecisions(hippoRoot, tenantId, opts = {}) {
         let rows;
         if (opts.status) {
             if (!VALID_DECISION_STATES.has(opts.status)) {
-                throw new Error(`loadDecisions: status must be one of ${Array.from(VALID_DECISION_STATES).join('|')}; got ${opts.status}`);
+                throw new BadRequestError(`loadDecisions: status must be one of ${Array.from(VALID_DECISION_STATES).join('|')}; got ${opts.status}`);
             }
             // SAFETY: rows' shape matches the columns named in DECISION_COLS above.
             rows = db.prepare(`

package/dist/dedupe.js

@@ -78,7 +78,7 @@ export function deduplicateStore(hippoRoot, options = {}) {
     const entriesByTenant = new Map();
     for (const entry of entries) {
         // EI2: also split by restricted scope, else a private copy can delete the readable one.
-        const key = derivationPartitionKey(entry.tenantId, entry.scope);
+        const key = derivationPartitionKey(entry.tenantId, entry.scope, entry.origin_project);
         const bucket = entriesByTenant.get(key);
         if (bucket)
             bucket.push(entry);

package/dist/doctor.js

@@ -10,10 +10,13 @@ import * as path from 'node:path';
 import { findHippoStoreDir } from './project-identity.js';
 import { getGlobalRoot } from './shared.js';
 import { isInitialized } from './store.js';
+import { loadConfig } from './config.js';
 import { openHippoDbReadOnly, closeHippoDb, getSchemaVersion, getCurrentSchemaVersion, countTableRows, IncompatibleBinaryError } from './db.js';
 import { REPLAY_AFTER_MS, TRANSCRIPT_FILL_WINDOW_MS } from './compaction-record.js';
 import { isEmbeddingAvailable } from './embeddings.js';
 import { CODEX_TRUST_LINE, codexHomeDir, isCodexPresent, isJsonObject } from './hooks.js';
+import { planUserGlobalRepair } from './project-merge.js';
+import { resolveTenantId } from './tenant.js';
 /** Minimum Node.js version hippo supports (package.json engines). */
 export const MIN_NODE = '22.16.0';
 function versionAtLeast(actual, min) {
@@ -127,6 +130,25 @@ function compactionsCheck(db, now) {
             : { id: 'compactions', status: 'warn', detail: `cannot read the compaction records: ${message}` };
     }
 }
+/** Merged rows older sleep saved as user-global, counted by the repair's own dry run so a truly user-global merge never warns. */
+function projectsCheck(globalRoot) {
+    let db = null;
+    try {
+        db = openHippoDbReadOnly(globalRoot);
+        const r = planUserGlobalRepair(db, resolveTenantId({}));
+        const n = r.toProject.length + r.setAside.length;
+        return n === 0
+            ? { id: 'projects', status: 'pass', detail: 'no merged memories in the global store are tagged user-global by mistake' }
+            : { id: 'projects', status: 'warn', detail: `${n} merged memories in the global store are tagged user-global, so every project's context can show them`, fix: 'hippo projects repair --global   (dry run; add --apply to write)' };
+    }
+    catch (err) {
+        return { id: 'projects', status: 'info', detail: `project tags not checked (${err instanceof Error ? err.message : String(err)})` };
+    }
+    finally {
+        if (db !== null)
+            closeHippoDb(db);
+    }
+}
 /** Run every check. Never throws for a broken install; broken parts become failed checks. */
 export function runDoctor(opts) {
     const cwd = opts.cwd ?? process.cwd();
@@ -208,6 +230,12 @@ export function runDoctor(opts) {
                 closeHippoDb(db);
         }
     }
+    const holdoutRateBp = store === null ? 0 : loadConfig(store).pilot.holdoutRateBp;
+    if (holdoutRateBp > 0) {
+        checks.push({ id: 'pilot', status: 'info', detail: `pilot holdout on: about ${holdoutRateBp / 100}% of sessions get no memories pushed by hippo (pilot.holdoutRateBp=${holdoutRateBp})` });
+    }
+    if (hasGlobal)
+        checks.push(projectsCheck(globalRoot));
     const claudeDir = path.join(home, '.claude');
     if (fs.existsSync(claudeDir)) {
         const settings = readJson(path.join(claudeDir, 'settings.json'));

package/dist/dormant.d.ts

@@ -19,8 +19,8 @@
  */
 import type { DatabaseSyncLike } from './db.js';
 import type { MemoryEntry } from './memory.js';
-/** Why a memory went dormant: sleep's decay pass, or an imported agent memory whose note was deleted. */
-export type DormantReason = 'decay' | 'source-deleted';
+/** Why a memory went dormant: sleep's decay pass, an imported agent memory whose note was deleted, or `hippo projects repair` splitting a two-project merge. */
+export type DormantReason = 'decay' | 'source-deleted' | 'project-repair';
 /** One memory that sleep is moving out of active memory into the dormant store. */
 export interface DormantMove {
     /** The memory as it stood when it faded; restored verbatim apart from its recall clock. */

package/dist/embedding-provider.js

@@ -33,6 +33,7 @@
 import { getEmbedding, isEmbeddingAvailable, resolveEmbeddingModel, DEFAULT_EMBEDDING_MODEL, } from './embeddings.js';
 import { loadConfig } from './config.js';
 import { redactSecrets } from './secret-detect.js';
+import { fetchWithRetry } from './http-retry.js';
 export const API_PROVIDER_KINDS = ['openai', 'voyage', 'cohere'];
 function isApiProviderKind(x) {
     return x === 'openai' || x === 'voyage' || x === 'cohere';
@@ -184,15 +185,14 @@ class ApiEmbeddingProvider {
         const url = `${this.baseUrl.replace(/\/$/, '')}/${spec.path}`;
         let resp;
         try {
-            resp = await fetch(url, {
+            resp = await fetchWithRetry(url, {
                 method: 'POST',
                 headers: {
                     'content-type': 'application/json',
                     authorization: `Bearer ${key}`,
                 },
                 body: JSON.stringify(spec.buildBody(this.model, chunk.map(redactSecrets), role)),
-                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-            });
+            }, { timeoutMs: REQUEST_TIMEOUT_MS });
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);

package/dist/embeddings.d.ts

@@ -4,6 +4,7 @@
  * Falls back silently if the library is not installed.
  */
 import { MemoryEntry } from './memory.js';
+import { type EmbeddingProvider } from './embedding-provider.js';
 export declare const DEFAULT_EMBEDDING_MODEL = "Xenova/all-MiniLM-L6-v2";
 export declare const EMBEDDING_MODEL_META_KEY = "embedding_model";
 /**
@@ -114,8 +115,7 @@ export declare function getEmbedding(text: string, model?: string, role?: Embedd
  */
 export declare function cosineSimilarity(a: number[], b: number[]): number;
 /**
- * Load the cached embedding index from disk.
- * Returns an empty object if the file doesn't exist or is corrupt.
+ * Load the cached embedding index; `{}` when the file is missing. A corrupt file is moved aside and rebuilt on the next embed; any other read error throws, so nothing saves over an index it could not read.
  */
 export declare function loadEmbeddingIndex(hippoRoot: string): Record<string, number[]>;
 /**
@@ -129,7 +129,7 @@ export declare function embedMemory(hippoRoot: string, entry: MemoryEntry, model
 /**
  * Embed all entries in hippoRoot that don't already have cached vectors.
  * Prunes orphaned embeddings for memories that no longer exist.
- * Returns the count of newly embedded entries.
+ * Returns the count of newly embedded entries. `provider` defaults to the store's configured one.
  */
-export declare function embedAll(hippoRoot: string, model?: string): Promise<number>;
+export declare function embedAll(hippoRoot: string, model?: string, provider?: EmbeddingProvider): Promise<number>;
 //# sourceMappingURL=embeddings.d.ts.map

package/dist/embeddings.js

@@ -13,6 +13,7 @@ import { initializeParticle, savePhysicsState, loadPhysicsState, resetAllPhysics
 import { loadConfig } from './config.js';
 import { resolveEmbeddingProvider } from './embedding-provider.js';
 import { redactSecretsStrict } from './secret-detect.js';
+import { log } from './log.js';
 // Use createRequire for synchronous module resolution check in ESM
 const _require = createRequire(import.meta.url);
 // Cached availability check
@@ -270,6 +271,9 @@ async function rebuildEmbeddingIndex(entries, provider) {
         if (vec && vec.length > 0) {
             rebuilt[entries[i].id] = vec;
         }
+        else {
+            noteSkippedEmbedding(entries[i].id);
+        }
     }
     return rebuilt;
 }
@@ -283,10 +287,15 @@ function resetPhysicsFromIndex(hippoRoot, entries, index) {
             closeHippoDb(db);
         }
     }
-    catch {
-        // Physics reset is best-effort; retrieval will still fall back gracefully.
+    catch (err) {
+        // Best effort: retrieval still falls back without physics state.
+        log.warn(`physics reset after reindex failed: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
+/** A provider's `[]` row is a swallowed per-item failure; name the memory so the gap can be traced. */
+function noteSkippedEmbedding(id) {
+    log.warn('memory not embedded; the next embed run retries it', { id });
+}
 /**
  * Get an embedding vector for a piece of text.
  * Returns an empty array if transformers is not available or fails.
@@ -314,7 +323,9 @@ export async function getEmbedding(text, model = DEFAULT_EMBEDDING_MODEL, role)
         // pipeline's documented tensor output shape.
         return Array.from(output.data);
     }
-    catch {
+    catch (err) {
+        // The caller sees `[]` and names the memory; the reason only shows at debug.
+        log.debug(`local embedding failed: ${err instanceof Error ? err.message : String(err)}`);
         return [];
     }
 }
@@ -340,23 +351,66 @@ export function cosineSimilarity(a, b) {
     return Math.min(1, Math.max(-1, dot / denom));
 }
 const EMBEDDINGS_FILE = 'embeddings.json';
+// Never equal to a real index identity, so the next embed run treats it as a model change and rebuilds every vector.
+const QUARANTINED_INDEX_IDENTITY = 'quarantined-corrupt-index';
+function isErrnoCode(err, code) {
+    return err instanceof Error && 'code' in err && err.code === code;
+}
+function parseEmbeddingIndex(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        // SAFETY: saveEmbeddingIndex is the only writer and always writes this shape; anything that is not an object is corrupt.
+        return parsed instanceof Object && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Move a corrupt index aside and flag a full rebuild, so no later save can write over the only copy of those bytes. */
+function quarantineCorruptIndex(hippoRoot, fp) {
+    const aside = `${fp}.corrupt-${new Date().toISOString().replace(/[:.]/g, '-')}-${process.pid}`;
+    try {
+        fs.renameSync(fp, aside);
+    }
+    catch (err) {
+        if (isErrnoCode(err, 'ENOENT'))
+            return;
+        // A rename blocked by an open handle (Windows) still gets a copy kept; if the copy fails too, the throw stops the save.
+        fs.copyFileSync(fp, aside, fs.constants.COPYFILE_EXCL);
+    }
+    log.error(`${EMBEDDINGS_FILE} could not be parsed; kept it as ${path.basename(aside)} and the next embed rebuilds the index`, { hippoRoot });
+    try {
+        const db = openHippoDb(hippoRoot);
+        try {
+            setMeta(db, EMBEDDING_MODEL_META_KEY, QUARANTINED_INDEX_IDENTITY);
+        }
+        finally {
+            closeHippoDb(db);
+        }
+    }
+    catch (err) {
+        log.warn(`could not flag the embedding index for rebuild; run 'hippo embed' to restore vectors (${err instanceof Error ? err.message : String(err)})`, { hippoRoot });
+    }
+}
 /**
- * Load the cached embedding index from disk.
- * Returns an empty object if the file doesn't exist or is corrupt.
+ * Load the cached embedding index; `{}` when the file is missing. A corrupt file is moved aside and rebuilt on the next embed; any other read error throws, so nothing saves over an index it could not read.
  */
 export function loadEmbeddingIndex(hippoRoot) {
     const fp = path.join(hippoRoot, EMBEDDINGS_FILE);
-    if (!fs.existsSync(fp))
-        return {};
+    let raw;
     try {
-        // SAFETY: embeddings.json is written exclusively by saveEmbeddingIndex with
-        // this exact shape; a corrupt or foreign file is caught by the try/catch
-        // below and treated as an empty index.
-        return JSON.parse(fs.readFileSync(fp, 'utf8'));
+        raw = fs.readFileSync(fp, 'utf8');
     }
-    catch {
-        return {};
+    catch (err) {
+        if (isErrnoCode(err, 'ENOENT'))
+            return {};
+        throw err;
     }
+    const index = parseEmbeddingIndex(raw);
+    if (index)
+        return index;
+    quarantineCorruptIndex(hippoRoot, fp);
+    return {};
 }
 /**
  * Save the embedding index to disk.
@@ -543,10 +597,9 @@ export async function embedMemory(hippoRoot, entry, model) {
 /**
  * Embed all entries in hippoRoot that don't already have cached vectors.
  * Prunes orphaned embeddings for memories that no longer exist.
- * Returns the count of newly embedded entries.
+ * Returns the count of newly embedded entries. `provider` defaults to the store's configured one.
  */
-export async function embedAll(hippoRoot, model) {
-    const provider = resolveEmbeddingProvider(hippoRoot, { model });
+export async function embedAll(hippoRoot, model, provider = resolveEmbeddingProvider(hippoRoot, { model })) {
     if (!provider.isAvailable()) {
         // A configured (non-disabled) API provider with a missing key is a
         // misconfiguration, not a no-op: surface it so programmatic callers of the
@@ -618,6 +671,9 @@ export async function embedAll(hippoRoot, model) {
                     dirty = true;
                     chunkDirty = true;
                 }
+                else {
+                    noteSkippedEmbedding(chunk[j].id);
+                }
             }
             if (chunkDirty)
                 saveEmbeddingIndex(hippoRoot, index);

package/dist/extract.js

@@ -3,6 +3,7 @@ import { writeEntry } from './store.js';
 import { loadConfig } from './config.js';
 import { RejectedValueError } from './rejection.js';
 import { redactSecrets } from './secret-detect.js';
+import { fetchWithRetry, llmTimeoutMs } from './http-retry.js';
 import { neverAutoShareTags } from './shared.js';
 function isJsonString(value) {
     return typeof value === 'string';
@@ -24,7 +25,7 @@ export async function extractFacts(text, opts) {
     const fetchFn = opts.fetcher ?? fetch;
     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',
@@ -36,7 +37,7 @@ export async function extractFacts(text, opts) {
                 max_tokens: 1200,
                 messages: [{ role: 'user', content: EXTRACTION_PROMPT + redactSecrets(text) }],
             }),
-        });
+        }, { timeoutMs: llmTimeoutMs(), fetchFn });
     }
     catch (err) {
         opts.onError?.(`request failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -91,22 +92,22 @@ export function storeExtractedFacts(hippoRoot, source, facts) {
     const baseHalfLifeDays = loadConfig(hippoRoot).defaultHalfLifeDays;
     for (const fact of facts) {
         const tags = ['extracted', ...inheritedTags, ...fact.tags];
-        const entry = createMemory(fact.content, {
-            layer: Layer.Semantic,
-            tags,
-            emotional_valence: fact.valence,
-            confidence: 'inferred',
-            source: source.source,
-            extracted_from: source.id,
-            scope: source.scope,
-            // T1 executor check (2026-08-15 hardening pass): same defect as the
-            // consolidate.ts merge/trace passes — createMemory with no tenantId
-            // option stamps 'default' (memory.ts:535) regardless of the source
-            // entry's own tenant. Thread it through so extracted facts land in
-            // the same tenant as the episodic memory they were extracted from.
-            tenantId: source.tenantId,
-            baseHalfLifeDays,
-        });
+        const entry = { ...createMemory(fact.content, {
+                layer: Layer.Semantic,
+                tags,
+                emotional_valence: fact.valence,
+                confidence: 'inferred',
+                source: source.source,
+                extracted_from: source.id,
+                scope: source.scope,
+                // T1 executor check (2026-08-15 hardening pass): same defect as the
+                // consolidate.ts merge/trace passes — createMemory with no tenantId
+                // option stamps 'default' (memory.ts:535) regardless of the source
+                // entry's own tenant. Thread it through so extracted facts land in
+                // the same tenant as the episodic memory they were extracted from.
+                tenantId: source.tenantId,
+                baseHalfLifeDays,
+            }), origin_project: source.origin_project };
         // AT1 containment: a refusal is per-VALUE — one rejected fact must not
         // drop the rest of this batch. writeEntry has already audited the
         // refusal (reject_refusal) before rethrowing, so skip-and-count here.

package/dist/http-retry.d.ts

@@ -0,0 +1,21 @@
+/** One retry policy for outbound HTTP: a timeout on every attempt, and backoff on 429 and 5xx only. */
+export interface RetryPolicy {
+    /** Per-attempt limit; a stalled peer ends as a thrown `TimeoutError`, never a hang. */
+    timeoutMs: number;
+    /** Total attempts including the first. */
+    attempts?: number;
+    baseDelayMs?: number;
+    /** A Retry-After longer than this hands the response back, so a caller with its own long pause keeps it. */
+    maxDelayMs?: number;
+    fetchFn?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    random?: () => number;
+}
+/** LLM calls (consolidation refine, DAG summaries, fact extraction) share one budget; `HIPPO_LLM_TIMEOUT_MS` overrides it. */
+export declare function llmTimeoutMs(): number;
+export declare function isRetryableStatus(status: number): boolean;
+/** Retry-After as milliseconds: delta-seconds or an HTTP date; null when absent or unreadable. */
+export declare function parseRetryAfterMs(header: string | null, now?: number): number | null;
+/** `fetch` with a per-attempt timeout and up to `attempts` tries on 429 and 5xx; the last response comes back as is and transport errors throw at once. */
+export declare function fetchWithRetry(url: string | URL, init: RequestInit, policy: RetryPolicy): Promise<Response>;
+//# sourceMappingURL=http-retry.d.ts.map

package/dist/http-retry.js

@@ -0,0 +1,50 @@
+/** One retry policy for outbound HTTP: a timeout on every attempt, and backoff on 429 and 5xx only. */
+const DEFAULT_ATTEMPTS = 3;
+const DEFAULT_BASE_DELAY_MS = 250;
+const DEFAULT_MAX_DELAY_MS = 8_000;
+const DEFAULT_LLM_TIMEOUT_MS = 60_000;
+/** LLM calls (consolidation refine, DAG summaries, fact extraction) share one budget; `HIPPO_LLM_TIMEOUT_MS` overrides it. */
+export function llmTimeoutMs() {
+    const parsed = Number.parseInt(process.env.HIPPO_LLM_TIMEOUT_MS ?? '', 10);
+    return parsed > 0 ? parsed : DEFAULT_LLM_TIMEOUT_MS;
+}
+export function isRetryableStatus(status) {
+    return status === 429 || (status >= 500 && status <= 599);
+}
+/** Retry-After as milliseconds: delta-seconds or an HTTP date; null when absent or unreadable. */
+export function parseRetryAfterMs(header, now = Date.now()) {
+    if (header === null || header.trim() === '')
+        return null;
+    const seconds = Number(header);
+    if (Number.isFinite(seconds))
+        return Math.max(0, seconds * 1000);
+    const at = Date.parse(header);
+    return Number.isNaN(at) ? null : Math.max(0, at - now);
+}
+const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** `fetch` with a per-attempt timeout and up to `attempts` tries on 429 and 5xx; the last response comes back as is and transport errors throw at once. */
+export async function fetchWithRetry(url, init, policy) {
+    const fetchFn = policy.fetchFn ?? fetch;
+    const attempts = Math.max(1, policy.attempts ?? DEFAULT_ATTEMPTS);
+    const baseDelayMs = policy.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+    const maxDelayMs = policy.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+    const sleep = policy.sleep ?? realSleep;
+    const random = policy.random ?? Math.random;
+    for (let attempt = 1;; attempt++) {
+        const timeout = AbortSignal.timeout(policy.timeoutMs);
+        const signal = init.signal ? AbortSignal.any([init.signal, timeout]) : timeout;
+        const res = await fetchFn(url, { ...init, signal });
+        if (!isRetryableStatus(res.status) || attempt >= attempts)
+            return res;
+        const retryAfter = parseRetryAfterMs(res.headers.get('retry-after'));
+        if (retryAfter !== null && retryAfter > maxDelayMs)
+            return res;
+        // Jitter over the upper half keeps parallel callers from retrying in lockstep.
+        const ceiling = Math.min(maxDelayMs, baseDelayMs * 2 ** (attempt - 1));
+        const delay = retryAfter ?? ceiling / 2 + random() * (ceiling / 2);
+        // Frees the pooled socket before the next attempt.
+        await res.body?.cancel();
+        await sleep(delay);
+    }
+}
+//# sourceMappingURL=http-retry.js.map

package/dist/http-util.d.ts

@@ -13,6 +13,14 @@ export declare class HttpError extends Error {
 }
 export declare class BodyTooLargeError extends Error {
 }
+/** The status and client-facing message for one failed request. */
+export interface ApiErrorReply {
+    status: number;
+    message: string;
+}
+export declare const INTERNAL_ERROR_MESSAGE = "internal server error";
+/** Maps by class so rewording a message never moves a status; an untyped error is a 500 whose text stays in the server log. */
+export declare function mapApiError<E>(err: E): ApiErrorReply;
 export declare function sendJson<T>(res: ServerResponse, status: number, body: T): void;
 /**
  * Read the entire request body into a Buffer. Caps at MAX_BODY_BYTES to keep

package/dist/http-util.js

@@ -1,3 +1,4 @@
+import { ApiError } from './api-errors.js';
 export function isJsonObjectRecord(value) {
     return value !== undefined && value !== null && typeof value === 'object' && !Array.isArray(value);
 }
@@ -19,6 +20,15 @@ export class HttpError extends Error {
 }
 export class BodyTooLargeError extends Error {
 }
+export const INTERNAL_ERROR_MESSAGE = 'internal server error';
+/** Maps by class so rewording a message never moves a status; an untyped error is a 500 whose text stays in the server log. */
+export function mapApiError(err) {
+    if (err instanceof HttpError || err instanceof ApiError)
+        return { status: err.status, message: err.message };
+    if (err instanceof BodyTooLargeError)
+        return { status: 413, message: err.message };
+    return { status: 500, message: INTERNAL_ERROR_MESSAGE };
+}
 export function sendJson(res, status, body) {
     res.writeHead(status, JSON_HEADERS);
     res.end(JSON.stringify(body));

package/dist/importers.d.ts

@@ -20,6 +20,8 @@ export interface ImportResult {
     /** K1 vault import: rows archived this run (changed + source-deleted). In a
      *  dryRun this is the would-be count (a true deletion-sync preview). */
     archived?: number;
+    /** Entries stored with secret-shaped text redacted; optional for the same published-surface reason as `rejected`. */
+    redacted?: number;
     entries: MemoryEntry[];
 }
 export interface ImportOptions {