hippo-memory 1.59.0 → 1.61.0

package/dist/embeddings.js

@@ -3,26 +3,20 @@
  * Uses @huggingface/transformers (local, zero API keys, ~22MB model).
  * Falls back silently if the library is not installed.
  */
+import { envByName } from './env.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import { randomUUID } from 'crypto';
-import { createRequire } from 'module';
-import { loadAllEntries } from './store.js';
+import { loadAllEntries } from './store/entry-reads.js';
 import { openHippoDb, closeHippoDb, getMeta, setMeta } from './db.js';
+import { EMBEDDING_MODEL_META_KEY, deleteOrphanVectors, hasStoredVectors, loadVectors, replaceAllVectors, storedVectorIds, upsertVectors, } from './vector-store.js';
 import { initializeParticle, savePhysicsState, loadPhysicsState, resetAllPhysicsState } from './physics-state.js';
 import { loadConfig } from './config.js';
 import { resolveEmbeddingProvider } from './embedding-provider.js';
+import { DEFAULT_EMBEDDING_MODEL } from './local-embedding.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
-let _embeddingAvailable = null;
-// Lazy-loaded pipeline (expensive to initialize)
-const _pipelineInstances = new Map();
-const _pipelineLoading = new Map();
-export const DEFAULT_EMBEDDING_MODEL = 'Xenova/all-MiniLM-L6-v2';
-export const EMBEDDING_MODEL_META_KEY = 'embedding_model';
+export { EMBEDDING_MODEL_META_KEY };
 /**
  * Bump whenever `embeddingInputText`'s composition changes in a way that
  * changes the resulting vectors for existing entries. Folded into the stored
@@ -75,148 +69,6 @@ export function embeddingInputText(entry) {
     const tags = entry.tags.filter((t) => !t.startsWith('path:'));
     return `${entry.content} ${tags.join(' ')}`.trim();
 }
-/**
- * Per-model pooling dispatch for Transformers.js's feature-extraction
- * pipeline. BGE family models were trained with CLS pooling (per BAAI's
- * official inference code in `FlagEmbedding`); MiniLM and most sentence-
- * transformers models use mean pooling. Unknown model ids default to mean
- * — that is the safe choice because most third-party models adopt the
- * sentence-transformers convention, and the alternative ('cls') silently
- * degrades vector quality for mean-pooling models.
- */
-export function poolingFor(model) {
-    return /\bbge\b/i.test(model) ? 'cls' : 'mean';
-}
-export function prefixFor(model, role) {
-    if (!role)
-        return '';
-    if (/\be5\b/i.test(model)) {
-        return role === 'query' ? 'query: ' : 'passage: ';
-    }
-    return '';
-}
-// Use Function constructor to bypass TypeScript static module resolution
-// for optional peer dependencies that may not be installed.
-// SAFETY: `import(s)` always resolves to a module namespace object (or rejects);
-// Promise<object> names that honestly without claiming a specific module shape.
-const _dynImport = new Function('s', 'return import(s)');
-/**
- * Check (synchronously) if @xenova/transformers or @huggingface/transformers is installed.
- */
-export function isEmbeddingAvailable() {
-    if (_embeddingAvailable !== null)
-        return _embeddingAvailable;
-    try {
-        _require.resolve('@xenova/transformers');
-        _embeddingAvailable = true;
-        return true;
-    }
-    catch {
-        // fall through
-    }
-    try {
-        _require.resolve('@huggingface/transformers');
-        _embeddingAvailable = true;
-        return true;
-    }
-    catch {
-        // fall through
-    }
-    _embeddingAvailable = false;
-    return false;
-}
-/**
- * Pick exactly one Transformers.js implementation before importing either.
- *
- * Importing both packages in one process loads incompatible native
- * onnxruntime-node versions (Xenova v2 uses ORT 1.14; Hugging Face v4 uses a
- * current ORT). Their finalizers can double-free an InferenceSession on exit.
- * Prefer the maintained package shipped by Hippo, with Xenova retained only as
- * a compatibility fallback for users who installed it themselves.
- */
-function resolveTransformersPackage() {
-    try {
-        _require.resolve('@huggingface/transformers');
-        return '@huggingface/transformers';
-    }
-    catch {
-        // fall through
-    }
-    try {
-        _require.resolve('@xenova/transformers');
-        return '@xenova/transformers';
-    }
-    catch {
-        return null;
-    }
-}
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-async function loadPipeline(model) {
-    if (_pipelineInstances.has(model))
-        return _pipelineInstances.get(model);
-    if (_pipelineLoading.has(model))
-        return _pipelineLoading.get(model);
-    const loading = (async () => {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const pkg = resolveTransformersPackage();
-        if (!pkg)
-            return null;
-        let pipelineFn = null;
-        try {
-            // SAFETY: the resolved module's shape is untyped by design (optional peer
-            // dependency); pipelineFn/mod.env are read defensively below and any
-            // failure to find a usable pipeline falls through to `return null`.
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const mod = await _dynImport(pkg);
-            if (process.env.HIPPO_MODEL_CACHE) {
-                if (mod.env) {
-                    mod.env.cacheDir = process.env.HIPPO_MODEL_CACHE;
-                    mod.env.localModelPath = process.env.HIPPO_MODEL_CACHE;
-                    mod.env.allowRemoteModels = false;
-                }
-            }
-            pipelineFn = mod.pipeline ?? mod.default?.pipeline;
-        }
-        catch {
-            return null;
-        }
-        if (!pipelineFn)
-            return null;
-        // The Qdrant-vendored bundle (used in egress-restricted sandboxes) ships
-        // only `onnx/model.onnx` (FP32). The HF default ships `model_quantized.onnx`
-        // too. When pointing at a local cache, pick the variant that's on disk.
-        const cacheRoot = process.env.HIPPO_MODEL_CACHE?.trim();
-        const quantized = !cacheRoot
-            || fs.existsSync(path.join(cacheRoot, model, 'onnx', 'model_quantized.onnx'));
-        try {
-            const instance = await pipelineFn('feature-extraction', model, { quantized });
-            _pipelineInstances.set(model, instance);
-            return instance;
-        }
-        catch {
-            return null;
-        }
-        finally {
-            _pipelineLoading.delete(model);
-        }
-    })();
-    _pipelineLoading.set(model, loading);
-    return loading;
-}
-export function resolveEmbeddingModel(hippoRoot, explicitModel) {
-    const direct = explicitModel?.trim();
-    if (direct)
-        return direct;
-    try {
-        const configured = loadConfig(hippoRoot).embeddings.model?.trim();
-        if (configured)
-            return configured;
-    }
-    catch {
-        // Fall back to the default model when config cannot be read.
-    }
-    return DEFAULT_EMBEDDING_MODEL;
-}
 function loadStoredEmbeddingModel(hippoRoot) {
     try {
         const db = openHippoDb(hippoRoot);
@@ -228,7 +80,8 @@ function loadStoredEmbeddingModel(hippoRoot) {
             closeHippoDb(db);
         }
     }
-    catch {
+    catch (err) {
+        log.debug(`stored embedding model unreadable: ${err instanceof Error ? err.message : String(err)}`);
         return null;
     }
 }
@@ -251,7 +104,8 @@ export function resolveIndexedEmbeddingModel(hippoRoot, index) {
     const stored = loadStoredEmbeddingModel(hippoRoot);
     if (stored)
         return stored;
-    return Object.keys(index ?? loadEmbeddingIndex(hippoRoot)).length > 0 ? DEFAULT_EMBEDDING_MODEL : null;
+    const hasVectors = index ? Object.keys(index).length > 0 : withVectorDb(hippoRoot, hasStoredVectors);
+    return hasVectors ? DEFAULT_EMBEDDING_MODEL : null;
 }
 export function embeddingModelRequiresReindex(hippoRoot, model, index) {
     const stored = resolveIndexedEmbeddingModel(hippoRoot, index);
@@ -296,39 +150,6 @@ function resetPhysicsFromIndex(hippoRoot, entries, index) {
 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.
- *
- * Pass `role: 'query'` / `'passage'` to engage asymmetric prefixing for
- * model families that require it (currently intfloat/e5-*). Omitting `role`
- * keeps the legacy symmetric behavior (no prefix), so BGE / MiniLM callers
- * don't need to change.
- */
-export async function getEmbedding(text, model = DEFAULT_EMBEDDING_MODEL, role) {
-    if (!isEmbeddingAvailable())
-        return [];
-    try {
-        const pipe = await loadPipeline(model);
-        if (!pipe)
-            return [];
-        const prefix = prefixFor(model, role);
-        const input = prefix ? `${prefix}${text}` : text;
-        // SAFETY: pipe() is a Transformers.js feature-extraction pipeline call;
-        // its untyped output is read defensively below (only `.data`, cast on
-        // the return line to the documented Float32Array tensor shape).
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const output = await pipe(input, { pooling: poolingFor(model), normalize: true });
-        // SAFETY: output.data is a Float32Array per the feature-extraction
-        // pipeline's documented tensor output shape.
-        return Array.from(output.data);
-    }
-    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 [];
-    }
-}
 /**
  * Cosine similarity between two vectors. Handles unnormalized vectors.
  * Returns 0 for empty or mismatched vectors.
@@ -350,85 +171,30 @@ export function cosineSimilarity(a, b) {
     // Clamp to [-1, 1] to handle floating point drift
     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 });
+function withVectorDb(hippoRoot, fn) {
+    const db = openHippoDb(hippoRoot);
     try {
-        const db = openHippoDb(hippoRoot);
-        try {
-            setMeta(db, EMBEDDING_MODEL_META_KEY, QUARANTINED_INDEX_IDENTITY);
-        }
-        finally {
-            closeHippoDb(db);
-        }
+        return fn(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 });
+    finally {
+        closeHippoDb(db);
     }
 }
-/**
- * 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.
- */
+/** Every stored vector keyed by memory id; `{}` when none. Search reads only the rows it ranks via `loadStoredVectors`. */
 export function loadEmbeddingIndex(hippoRoot) {
-    const fp = path.join(hippoRoot, EMBEDDINGS_FILE);
-    let raw;
-    try {
-        raw = fs.readFileSync(fp, 'utf8');
-    }
-    catch (err) {
-        if (isErrnoCode(err, 'ENOENT'))
-            return {};
-        throw err;
-    }
-    const index = parseEmbeddingIndex(raw);
-    if (index)
-        return index;
-    quarantineCorruptIndex(hippoRoot, fp);
-    return {};
+    return Object.fromEntries(withVectorDb(hippoRoot, (db) => loadVectors(db)));
 }
-/**
- * Save the embedding index to disk.
- */
-export function saveEmbeddingIndex(hippoRoot, index) {
-    const fp = path.join(hippoRoot, EMBEDDINGS_FILE);
-    const tmp = fp + '.tmp';
-    fs.writeFileSync(tmp, JSON.stringify(index), 'utf8');
-    try {
-        fs.renameSync(tmp, fp);
-    }
-    catch (err) {
-        try {
-            fs.unlinkSync(tmp);
-        }
-        catch { /* best-effort cleanup */ }
-        throw err;
-    }
+/** Stored vectors for `ids` only. */
+export function loadStoredVectors(hippoRoot, ids) {
+    return ids.length === 0 ? new Map() : withVectorDb(hippoRoot, (db) => loadVectors(db, ids));
+}
+/** Whether the store holds any vector at all. */
+export function hasEmbeddings(hippoRoot) {
+    return withVectorDb(hippoRoot, hasStoredVectors);
+}
+/** Replace every stored vector with `index`; `model` defaults to the stored index identity. */
+export function saveEmbeddingIndex(hippoRoot, index, model) {
+    withVectorDb(hippoRoot, (db) => replaceAllVectors(db, index, model ?? getMeta(db, EMBEDDING_MODEL_META_KEY, '')));
 }
 const EMBED_LOCK_FILE = 'embeddings.lock';
 const EMBED_LOCK_WAIT_MS = 10_000;
@@ -492,7 +258,7 @@ async function acquireEmbedFileLock(hippoRoot) {
             continue;
         }
         if (Date.now() >= deadline)
-            throw new Error(`embeddings.json is busy: another hippo process holds ${lockPath}`);
+            throw new Error(`the embedding index is busy: another hippo process holds ${lockPath}`);
         await new Promise((r) => setTimeout(r, 50));
     }
 }
@@ -523,7 +289,7 @@ function warnEmbedFailureOnce(source, rawMessage) {
     _embedFailureWarned = true;
     // Strict scrub: this line can land in a hook log file, and an API may echo the key back in its error body.
     const message = redactSecretsStrict(rawMessage).replace(/\s+/g, ' ').replace(/\.+$/, '');
-    console.error(`hippo: embedding failed (${source}): ${message}. Memories are stored without embeddings until this is fixed.`);
+    log.warn(`embedding failed (${source}): ${message}. Memories are stored without embeddings until this is fixed.`);
 }
 /**
  * Embed a single memory entry and cache the result in the embedding index.
@@ -547,15 +313,14 @@ export async function embedMemory(hippoRoot, entry, model) {
         // where failures surface. On any failure we leave the existing index as-is.
         try {
             const identity = provider.id;
-            const existingIndex = loadEmbeddingIndex(hippoRoot);
-            if (embeddingModelRequiresReindex(hippoRoot, identity, existingIndex)) {
+            if (embeddingModelRequiresReindex(hippoRoot, identity)) {
                 // L9: host-wide rebuild. The embedding index is keyed by entry.id
                 // (which is tenant-scoped) but the index itself is one per hippoRoot.
                 // Cross-tenant content equivalence is visible at the vector level.
                 // Per-tenant indices would be a larger architecture change.
                 const entries = loadAllEntries(hippoRoot);
                 const rebuiltIndex = await rebuildEmbeddingIndex(entries, provider);
-                saveEmbeddingIndex(hippoRoot, rebuiltIndex);
+                saveEmbeddingIndex(hippoRoot, rebuiltIndex, embeddingIndexIdentity(identity));
                 saveStoredEmbeddingModel(hippoRoot, identity);
                 resetPhysicsFromIndex(hippoRoot, entries, rebuiltIndex);
                 return;
@@ -564,9 +329,7 @@ export async function embedMemory(hippoRoot, entry, model) {
             const [vector] = await provider.embed([text], 'passage');
             if (!vector || vector.length === 0)
                 return;
-            const index = existingIndex;
-            index[entry.id] = vector;
-            saveEmbeddingIndex(hippoRoot, index);
+            withVectorDb(hippoRoot, (db) => upsertVectors(db, [[entry.id, vector]], embeddingIndexIdentity(identity)));
             saveStoredEmbeddingModel(hippoRoot, identity);
             // Initialize physics state for this memory
             try {
@@ -591,7 +354,7 @@ export async function embedMemory(hippoRoot, entry, model) {
             warnEmbedFailureOnce(provider.kind, err instanceof Error ? err.message : String(err));
         }
     }).catch((err) => {
-        console.error(`hippo: skipped embedding ${entry.id} (${err instanceof Error ? err.message : String(err)}); run 'hippo embed' to backfill`);
+        log.warn(`skipped embedding ${entry.id} (${err instanceof Error ? err.message : String(err)}); run 'hippo embed' to backfill`);
     });
 }
 /**
@@ -609,7 +372,7 @@ export async function embedAll(hippoRoot, model, provider = resolveEmbeddingProv
         if (provider.kind !== 'local' &&
             cfg.enabled !== false &&
             provider.keyEnv &&
-            !process.env[provider.keyEnv]?.trim()) {
+            !envByName(provider.keyEnv)?.trim()) {
             throw new Error(`Embedding provider '${provider.kind}' is configured but ${provider.keyEnv} is not set.`);
         }
         return 0;
@@ -620,30 +383,25 @@ export async function embedAll(hippoRoot, model, provider = resolveEmbeddingProv
         // entries into the per-host embedding index. Per-tenant filtering would
         // produce partial indices and break recall.
         const entries = loadAllEntries(hippoRoot);
-        const index = loadEmbeddingIndex(hippoRoot);
-        if (embeddingModelRequiresReindex(hippoRoot, identity, index)) {
+        const model = embeddingIndexIdentity(identity);
+        if (embeddingModelRequiresReindex(hippoRoot, identity)) {
             const rebuiltIndex = await rebuildEmbeddingIndex(entries, provider);
-            saveEmbeddingIndex(hippoRoot, rebuiltIndex);
+            saveEmbeddingIndex(hippoRoot, rebuiltIndex, model);
             saveStoredEmbeddingModel(hippoRoot, identity);
             resetPhysicsFromIndex(hippoRoot, entries, rebuiltIndex);
             return Object.keys(rebuiltIndex).length;
         }
-        let dirty = false;
-        // Prune orphaned embeddings for deleted memories
-        const activeIds = new Set(entries.map((e) => e.id));
-        for (const id of Object.keys(index)) {
-            if (!activeIds.has(id)) {
-                delete index[id];
-                dirty = true;
-            }
-        }
+        const embedded = withVectorDb(hippoRoot, (db) => {
+            deleteOrphanVectors(db);
+            return storedVectorIds(db);
+        });
         // Embed entries without a cached vector in save-checkpointed chunks.
         // provider.embed batches internally (one HTTP request per batchSize for API
         // providers; sequential for local). A `[]` row means that single item could
         // not be embedded and is left for a later run (resumable). On a hard provider
         // failure mid-backfill we persist the chunks already embedded this run rather
         // than discarding paid progress, then stop and resume on the next run.
-        const pending = entries.filter((e) => !index[e.id]);
+        const pending = entries.filter((e) => !embedded.has(e.id));
         let count = 0;
         // Initialized to `undefined` (not a known-evidence literal like `null`) so
         // it stays a plain `unknown` binding for the arbitrary caught value below;
@@ -662,24 +420,15 @@ export async function embedAll(hippoRoot, model, provider = resolveEmbeddingProv
                 backfillError = err;
                 break;
             }
-            let chunkDirty = false;
+            const rows = [];
             for (let j = 0; j < chunk.length; j++) {
                 const vec = vectors[j];
-                if (vec && vec.length > 0) {
-                    index[chunk[j].id] = vec;
-                    count++;
-                    dirty = true;
-                    chunkDirty = true;
-                }
-                else {
+                if (vec && vec.length > 0)
+                    rows.push([chunk[j].id, vec]);
+                else
                     noteSkippedEmbedding(chunk[j].id);
-                }
             }
-            if (chunkDirty)
-                saveEmbeddingIndex(hippoRoot, index);
-        }
-        if (dirty) {
-            saveEmbeddingIndex(hippoRoot, index);
+            count += withVectorDb(hippoRoot, (db) => upsertVectors(db, rows, model));
         }
         saveStoredEmbeddingModel(hippoRoot, identity);
         // Partial progress is now persisted; surface a hard backfill failure so the

package/dist/env.d.ts

@@ -0,0 +1,75 @@
+/** The whole environment, for code that takes it as an injectable map (agent-memory machines, owner checks, support bundles). */
+export declare function processEnv(): NodeJS.ProcessEnv;
+/** A variable whose name comes from configuration, such as an embedding provider's key variable. */
+export declare function envByName(name: string): string | undefined;
+export declare function envAblateDecay(): boolean;
+export declare function envAblateRecallBoost(): boolean;
+export declare function envAblateOutcome(): boolean;
+export declare function envAblateOutcomeSlow(): boolean;
+export declare function envAblateOutcomeFast(): boolean;
+export declare function envAblateRecency(): boolean;
+/** HIPPO_EVAL_RECENCY_DAYS when it is a positive number, else null. */
+export declare function envEvalRecencyDays(): number | null;
+/** HIPPO_FAKE_NOW as epoch millis, or null unless it is byte-identical to Date.toISOString output. */
+export declare function envFakeNowMs(): number | null;
+export declare function envTestDeliveryFault(): string;
+export declare function envForceLikePath(): boolean;
+export declare function envLossAversionRatio(): string | undefined;
+export declare function envSummaryDeboost(): string | undefined;
+export declare function envAutodebiasOff(): boolean;
+export declare function envAnchoringOff(): boolean;
+export declare function envAvailabilityOff(): boolean;
+export declare function envDagRebuildCap(): number | undefined;
+export declare function envHippoHome(): string | undefined;
+export declare function envXdgDataHome(): string | undefined;
+export declare function envHomeDir(): string | undefined;
+export declare function envPath(): string | undefined;
+export declare function envModelCache(): string | undefined;
+export declare function envHippoSessionId(): string | undefined;
+export declare function envClaudeCodeSessionId(): string | undefined;
+export declare function envScope(): string | undefined;
+export declare function envGstackSkill(): string | undefined;
+export declare function envOpenclawSkill(): string | undefined;
+/** HIPPO_TENANT trimmed; empty or whitespace-only falls through to 'default'. */
+export declare function envTenant(): string;
+export declare function envSkipAutoIntegrations(): boolean;
+export declare function envSkipPostinstall(): boolean;
+export declare function envMcpStdio(): boolean;
+/** Any non-empty value counts, unlike the `=1` switches. */
+export declare function envRequireServer(): boolean;
+export declare function envRequireSessionScopedFreshTail(): boolean;
+export declare function envStdinWaitMs(): number | undefined;
+export declare function envLogLevel(): string;
+export declare function envPort(): string | undefined;
+export declare function envRequireAuth(): boolean;
+export declare function envV1Rps(): string | undefined;
+export declare function envApiKey(): string | undefined;
+export declare function envClientIpHeader(): string | undefined;
+export declare function envTrustedProxies(): string | undefined;
+export declare function envMcpSseMaxStreams(): number | undefined;
+export declare function envMcpSseHeartbeatMs(): number | undefined;
+export declare function envMcpSseMaxAgeSec(): number | undefined;
+export declare function envAnthropicApiKey(): string | undefined;
+export declare function envLlmTimeoutMs(): number | undefined;
+export declare function envTypesafeApiKey(): string | undefined;
+export declare function envJevTimeoutMs(): number | undefined;
+export declare function envJevModel(): string | undefined;
+export declare function envLlmRerankerUrl(): string | undefined;
+export declare function envLlmRerankerKey(): string | undefined;
+export declare function envLlmRerankerModel(): string | undefined;
+export declare function envLlmRerankerTimeoutMs(): number | undefined;
+export declare function envClefEndpoint(): string | undefined;
+export declare function envClefEndpointToken(): string | undefined;
+export declare function envClefTimeoutMs(): string | undefined;
+export declare function envCloudflareAccountId(): string;
+export declare function envCloudflareApiToken(): string;
+export declare function envSlackBotToken(): string | undefined;
+export declare function envSlackTeamId(): string | undefined;
+export declare function envSlackSigningSecret(): string | undefined;
+export declare function envSlackSigningSecretPrevious(): string | undefined;
+export declare function envSlackAllowUnknownTeamFallback(): boolean;
+export declare function envGithubToken(): string | undefined;
+export declare function envGithubWebhookSecret(): string | undefined;
+export declare function envGithubWebhookSecretPrevious(): string | undefined;
+export declare function envGithubAllowUnknownInstallationFallback(): boolean;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.js

@@ -0,0 +1,119 @@
+// The one module in src/ that reads process.env; scripts/check-env-reads.mjs fails CI on any other read.
+// Accessors read at call time, so a test that sets a variable between cases, or a HIPPO_HOME switch mid-process, still holds.
+function raw(name) {
+    return process.env[name];
+}
+function isOne(name) {
+    return raw(name) === '1';
+}
+function isOneOrTrue(name) {
+    const value = raw(name);
+    return value === '1' || value === 'true';
+}
+/** parseInt, kept only when above zero; the caller supplies its own default. */
+function positiveInt(name) {
+    const parsed = Number.parseInt(raw(name) ?? '', 10);
+    return parsed > 0 ? parsed : undefined;
+}
+/** parseInt, kept when nonzero: these sites have always used `|| default`, so a negative value passes through. */
+function nonZeroInt(name) {
+    return Number.parseInt(raw(name) ?? '', 10) || undefined;
+}
+/** The whole environment, for code that takes it as an injectable map (agent-memory machines, owner checks, support bundles). */
+export function processEnv() {
+    return process.env;
+}
+/** A variable whose name comes from configuration, such as an embedding provider's key variable. */
+export function envByName(name) {
+    return raw(name);
+}
+// Eval-only lifecycle switches; ablation.ts caches them per process.
+export function envAblateDecay() { return isOneOrTrue('HIPPO_ABLATE_DECAY'); }
+export function envAblateRecallBoost() { return isOneOrTrue('HIPPO_ABLATE_RECALL_BOOST'); }
+export function envAblateOutcome() { return isOneOrTrue('HIPPO_ABLATE_OUTCOME'); }
+export function envAblateOutcomeSlow() { return isOneOrTrue('HIPPO_ABLATE_OUTCOME_SLOW'); }
+export function envAblateOutcomeFast() { return isOneOrTrue('HIPPO_ABLATE_OUTCOME_FAST'); }
+export function envAblateRecency() { return isOneOrTrue('HIPPO_ABLATE_RECENCY'); }
+/** HIPPO_EVAL_RECENCY_DAYS when it is a positive number, else null. */
+export function envEvalRecencyDays() {
+    const days = Number(raw('HIPPO_EVAL_RECENCY_DAYS'));
+    return Number.isFinite(days) && days > 0 ? days : null;
+}
+/** HIPPO_FAKE_NOW as epoch millis, or null unless it is byte-identical to Date.toISOString output. */
+export function envFakeNowMs() {
+    const value = raw('HIPPO_FAKE_NOW');
+    if (value === undefined || value === '')
+        return null;
+    // Round-trip, not a regex: Date.parse accepts junk and locale dates, and a regex admits rolled-over days like 02-31.
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) && new Date(parsed).toISOString() === value ? parsed : null;
+}
+export function envTestDeliveryFault() { return raw('HIPPO_TEST_DELIVERY_FAULT') ?? ''; }
+export function envForceLikePath() { return isOne('HIPPO_FORCE_LIKE_PATH'); }
+export function envLossAversionRatio() { return raw('HIPPO_LOSS_AVERSION_RATIO'); }
+export function envSummaryDeboost() { return raw('HIPPO_SUMMARY_DEBOOST'); }
+export function envAutodebiasOff() { return raw('HIPPO_AUTODEBIAS') === 'off'; }
+export function envAnchoringOff() { return raw('HIPPO_ANCHORING') === 'off'; }
+export function envAvailabilityOff() { return raw('HIPPO_AVAILABILITY') === 'off'; }
+export function envDagRebuildCap() { return positiveInt('HIPPO_DAG_REBUILD_CAP'); }
+// Paths. HIPPO_HOME and XDG_DATA_HOME come back trimmed, possibly empty.
+export function envHippoHome() { return raw('HIPPO_HOME')?.trim(); }
+export function envXdgDataHome() { return raw('XDG_DATA_HOME')?.trim(); }
+export function envHomeDir() { return raw('HOME') || raw('USERPROFILE'); }
+export function envPath() { return raw('PATH'); }
+export function envModelCache() { return raw('HIPPO_MODEL_CACHE'); }
+// Session, scope and tenant.
+export function envHippoSessionId() { return raw('HIPPO_SESSION_ID'); }
+export function envClaudeCodeSessionId() { return raw('CLAUDE_CODE_SESSION_ID'); }
+export function envScope() { return raw('HIPPO_SCOPE'); }
+export function envGstackSkill() { return raw('GSTACK_SKILL'); }
+export function envOpenclawSkill() { return raw('OPENCLAW_SKILL'); }
+/** HIPPO_TENANT trimmed; empty or whitespace-only falls through to 'default'. */
+export function envTenant() {
+    return raw('HIPPO_TENANT')?.trim() || 'default';
+}
+// Install and CLI switches.
+export function envSkipAutoIntegrations() { return isOne('HIPPO_SKIP_AUTO_INTEGRATIONS'); }
+export function envSkipPostinstall() { return isOne('HIPPO_SKIP_POSTINSTALL'); }
+export function envMcpStdio() { return isOne('HIPPO_MCP_STDIO'); }
+/** Any non-empty value counts, unlike the `=1` switches. */
+export function envRequireServer() { return Boolean(raw('HIPPO_REQUIRE_SERVER')); }
+export function envRequireSessionScopedFreshTail() { return isOne('HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL'); }
+export function envStdinWaitMs() { return positiveInt('HIPPO_STDIN_WAIT_MS'); }
+export function envLogLevel() { return raw('HIPPO_LOG')?.trim().toLowerCase() ?? ''; }
+// Server.
+export function envPort() { return raw('HIPPO_PORT'); }
+export function envRequireAuth() { return isOne('HIPPO_REQUIRE_AUTH'); }
+export function envV1Rps() { return raw('HIPPO_V1_RPS'); }
+export function envApiKey() { return raw('HIPPO_API_KEY'); }
+export function envClientIpHeader() { return raw('HIPPO_CLIENT_IP_HEADER')?.trim().toLowerCase(); }
+export function envTrustedProxies() { return raw('HIPPO_TRUSTED_PROXIES'); }
+export function envMcpSseMaxStreams() { return positiveInt('MCP_SSE_MAX_STREAMS'); }
+export function envMcpSseHeartbeatMs() { return nonZeroInt('MCP_SSE_HEARTBEAT_MS'); }
+export function envMcpSseMaxAgeSec() { return nonZeroInt('MCP_SSE_MAX_AGE_SEC'); }
+// LLM and reranker credentials and knobs.
+export function envAnthropicApiKey() { return raw('ANTHROPIC_API_KEY'); }
+export function envLlmTimeoutMs() { return positiveInt('HIPPO_LLM_TIMEOUT_MS'); }
+export function envTypesafeApiKey() { return raw('TYPESAFE_API_KEY'); }
+export function envJevTimeoutMs() { return positiveInt('HIPPO_JEV_TIMEOUT_MS'); }
+export function envJevModel() { return raw('HIPPO_JEV_MODEL'); }
+export function envLlmRerankerUrl() { return raw('HIPPO_LLM_RERANKER_URL'); }
+export function envLlmRerankerKey() { return raw('HIPPO_LLM_RERANKER_KEY'); }
+export function envLlmRerankerModel() { return raw('HIPPO_LLM_RERANKER_MODEL'); }
+export function envLlmRerankerTimeoutMs() { return nonZeroInt('HIPPO_LLM_RERANKER_TIMEOUT_MS'); }
+export function envClefEndpoint() { return raw('HIPPO_CLEF_ENDPOINT')?.trim(); }
+export function envClefEndpointToken() { return raw('HIPPO_CLEF_ENDPOINT_TOKEN')?.trim() || undefined; }
+export function envClefTimeoutMs() { return raw('HIPPO_CLEF_TIMEOUT_MS'); }
+export function envCloudflareAccountId() { return raw('CLOUDFLARE_ACCOUNT_ID')?.trim() ?? ''; }
+export function envCloudflareApiToken() { return raw('CLOUDFLARE_API_TOKEN')?.trim() ?? ''; }
+// Connectors.
+export function envSlackBotToken() { return raw('SLACK_BOT_TOKEN'); }
+export function envSlackTeamId() { return raw('SLACK_TEAM_ID'); }
+export function envSlackSigningSecret() { return raw('SLACK_SIGNING_SECRET'); }
+export function envSlackSigningSecretPrevious() { return raw('SLACK_SIGNING_SECRET_PREVIOUS'); }
+export function envSlackAllowUnknownTeamFallback() { return isOne('SLACK_ALLOW_UNKNOWN_TEAM_FALLBACK'); }
+export function envGithubToken() { return raw('GITHUB_TOKEN'); }
+export function envGithubWebhookSecret() { return raw('GITHUB_WEBHOOK_SECRET'); }
+export function envGithubWebhookSecretPrevious() { return raw('GITHUB_WEBHOOK_SECRET_PREVIOUS'); }
+export function envGithubAllowUnknownInstallationFallback() { return isOne('GITHUB_ALLOW_UNKNOWN_INSTALLATION_FALLBACK'); }
+//# sourceMappingURL=env.js.map