hippo-memory 1.70.0 → 1.71.0

package/dist/db/physics-state.js

@@ -1,16 +1,10 @@
-/**
- * Physics state persistence for Hippo.
- * Stores and loads particle state (position, velocity, mass, charge, temperature)
- * in SQLite using BLOB columns for 384-dim vectors.
- */
+/** Physics state persistence: particle state (position, velocity, mass, charge, temperature) in SQLite, with BLOB columns for 384-dim vectors. */
 import { evalNow } from '../core/ablation.js';
 import { withWriteScope } from './busy.js';
 import { computeMass, computeCharge, computeTemperature, vecZero } from '../core/physics.js';
 import { calculateStrength } from '../core/memory.js';
 import { DAY_MS } from '../util/time.js';
-// ---------------------------------------------------------------------------
 // Float32Array <-> Buffer serialization
-// ---------------------------------------------------------------------------
 export function float32ToBuffer(arr) {
     const f32 = new Float32Array(arr);
     return Buffer.from(f32.buffer);
@@ -24,13 +18,8 @@ export function bufferToFloat32(buf) {
     new Uint8Array(aligned).set(bytes);
     return Array.from(new Float32Array(aligned));
 }
-// ---------------------------------------------------------------------------
 // Schema migration
-// ---------------------------------------------------------------------------
-/**
- * Create the memory_physics table (migration v8).
- * Call this from db.ts MIGRATIONS array.
- */
+/** Create the memory_physics table (migration v8). */
 export function createPhysicsTable(db) {
     db.exec(`
     CREATE TABLE IF NOT EXISTS memory_physics (
@@ -108,10 +97,7 @@ export function savePhysicsState(db, particles) {
         }
     });
 }
-/**
- * Initialize physics state for a memory from its embedding vector.
- * Returns the new particle (does not persist — caller must save).
- */
+/** Initialize physics state for a memory from its embedding vector; returns the new particle without persisting (the caller must save). */
 export function initializeParticle(entry, embedding, now = evalNow()) {
     const strength = calculateStrength(entry, now);
     const ageDays = (now.getTime() - new Date(entry.created).getTime()) / DAY_MS;
@@ -125,28 +111,31 @@ export function initializeParticle(entry, embedding, now = evalNow()) {
         lastSimulation: now.toISOString(),
     };
 }
-/**
- * Reset all physics states from original embeddings.
- * Drops existing physics data and re-initializes from the embedding index.
- */
+const RESET_BATCH = 64;
+/** Drops every particle, then seeds one per entry that has an embedding; `entries` may be read lazily, as each batch is written before the next is read. */
 export function resetAllPhysicsState(db, entries, embeddingIndex, now = evalNow()) {
     db.exec('DELETE FROM memory_physics');
-    const particles = [];
-    for (const entry of entries) {
-        const embedding = embeddingIndex[entry.id];
-        if (!embedding || embedding.length === 0)
-            continue;
-        particles.push(initializeParticle(entry, embedding, now));
-    }
-    if (particles.length > 0) {
-        savePhysicsState(db, particles);
-    }
-    return particles.length;
+    // One transaction for every batch, so a failure part way leaves no particles rather than some.
+    return withWriteScope(db, 'reset_particles', () => {
+        let count = 0;
+        let batch = [];
+        const flush = () => {
+            savePhysicsState(db, batch);
+            count += batch.length;
+            batch = [];
+        };
+        for (const entry of entries) {
+            const embedding = embeddingIndex[entry.id];
+            if (!embedding || embedding.length === 0)
+                continue;
+            if (batch.push(initializeParticle(entry, embedding, now)) === RESET_BATCH)
+                flush();
+        }
+        flush();
+        return count;
+    });
 }
-/**
- * Refresh mass, charge, and temperature for existing particles
- * based on current memory attributes (called during consolidation).
- */
+/** Refresh mass, charge and temperature for existing particles from current memory attributes (called during consolidation). */
 export function refreshParticleProperties(particles, entries, now = evalNow()) {
     for (const p of particles) {
         const entry = entries.get(p.memoryId);

package/dist/db/raw-archive-mirror-cleanup.d.ts

@@ -1,20 +1,5 @@
 import type { DatabaseSyncLike } from './index.js';
-/**
- * Path A backfill cleanup: existing raw_archive rows that were archived BEFORE
- * commit 70180b5 left their markdown mirrors at <hippoRoot>/<layer>/<id>.md
- * with original content intact. The DB is already redacted via migration v20;
- * this function deletes those filesystem mirrors so RTBF holds for historical
- * archives too.
- *
- * Per-row tracking via raw_archive.mirror_cleaned_at (added in v21):
- *   - SELECT only rows WHERE mirror_cleaned_at IS NULL.
- *   - On success (every layer either deleted or didn't exist), UPDATE the row
- *     with the cleanup timestamp.
- *   - On any unlink failure, leave mirror_cleaned_at NULL so the next
- *     connection retries. Warn (capped at MAX_WARN_LOGS rows per call).
- *
- * Returns whether every pending row was cleaned; the SELECT has no index to
- * use, so a connection runs it only when the archive has changed since.
- */
+/** Path A backfill cleanup: delete markdown mirrors (<hippoRoot>/<layer>/<id>.md) of rows archived before redaction, so RTBF holds for historical archives.
+ * Tracked by raw_archive.mirror_cleaned_at: set only on success, so a failed unlink retries next connection. Returns whether all pending rows were cleaned. */
 export declare function cleanupArchivedMirrors(hippoRoot: string, db: DatabaseSyncLike): boolean;
 //# sourceMappingURL=raw-archive-mirror-cleanup.d.ts.map

package/dist/db/raw-archive-mirror-cleanup.js

@@ -3,23 +3,8 @@ import * as path from 'path';
 import { errorMessage, log } from '../util/log.js';
 const LAYERS = ['episodic', 'buffer', 'semantic'];
 const MAX_WARN_LOGS = 5;
-/**
- * Path A backfill cleanup: existing raw_archive rows that were archived BEFORE
- * commit 70180b5 left their markdown mirrors at <hippoRoot>/<layer>/<id>.md
- * with original content intact. The DB is already redacted via migration v20;
- * this function deletes those filesystem mirrors so RTBF holds for historical
- * archives too.
- *
- * Per-row tracking via raw_archive.mirror_cleaned_at (added in v21):
- *   - SELECT only rows WHERE mirror_cleaned_at IS NULL.
- *   - On success (every layer either deleted or didn't exist), UPDATE the row
- *     with the cleanup timestamp.
- *   - On any unlink failure, leave mirror_cleaned_at NULL so the next
- *     connection retries. Warn (capped at MAX_WARN_LOGS rows per call).
- *
- * Returns whether every pending row was cleaned; the SELECT has no index to
- * use, so a connection runs it only when the archive has changed since.
- */
+/** Path A backfill cleanup: delete markdown mirrors (<hippoRoot>/<layer>/<id>.md) of rows archived before redaction, so RTBF holds for historical archives.
+ * Tracked by raw_archive.mirror_cleaned_at: set only on success, so a failed unlink retries next connection. Returns whether all pending rows were cleaned. */
 export function cleanupArchivedMirrors(hippoRoot, db) {
     // SAFETY: the SELECT above names exactly one column, memory_id (raw_archive.memory_id
     // is NOT NULL TEXT), so the row shape matches this assertion.

package/dist/db/vector-store.d.ts

@@ -15,6 +15,8 @@ export declare function loadVectors(db: DatabaseSyncLike, ids?: readonly string[
 /** `loadVectors` for `ids` with no copy: each value views the bytes the store returned for that row. */
 export declare function loadVectorViews(db: DatabaseSyncLike, ids: readonly string[]): Map<string, Float32Array>;
 export declare function storedVectorIds(db: DatabaseSyncLike): Set<string>;
+/** Float count of the first stored row, from its blob length; the vector is never read. */
+export declare function storedVectorDims(db: DatabaseSyncLike): number | undefined;
 export declare function hasStoredVectors(db: DatabaseSyncLike): boolean;
 export interface VectorMatch {
     id: string;

package/dist/db/vector-store.js

@@ -85,6 +85,12 @@ export function storedVectorIds(db) {
     // SAFETY: the SELECT names exactly the one column read.
     return new Set(db.prepare('SELECT memory_id FROM memory_vectors').all().map((r) => r.memory_id));
 }
+/** Float count of the first stored row, from its blob length; the vector is never read. */
+export function storedVectorDims(db) {
+    // SAFETY: the SELECT names exactly the one column read.
+    const row = db.prepare('SELECT length(vector) AS bytes FROM memory_vectors LIMIT 1').get();
+    return row === undefined ? undefined : Math.floor(row.bytes / 4);
+}
 export function hasStoredVectors(db) {
     return db.prepare('SELECT 1 FROM memory_vectors LIMIT 1').get() !== undefined;
 }
@@ -141,7 +147,8 @@ export async function topVectorMatches(db, query, k, where, params) {
     const best = bestMatches(query, k);
     if (!best)
         return [];
-    // SHORTCUT: brute-force cosine over every admitted vector, a chunk per event-loop turn; latency still grows with rows, fine to ~100k, and an ANN index (sqlite-vec, HNSW) is the upgrade.
+    // SHORTCUT: brute-force cosine over every admitted vector, a chunk per event-loop turn; latency
+    // still grows with rows, fine to ~100k, and an ANN index (sqlite-vec, HNSW) is the upgrade.
     // SAFETY: the SELECT names exactly these two columns; node:sqlite returns BLOBs as Uint8Array.
     const rows = db.prepare(`
     SELECT v.memory_id AS id, v.vector AS vector

package/dist/doctor.js

@@ -1,14 +1,10 @@
-/**
- * `hippo doctor`: a health check people and agents can run after installing
- * hippo, or when something seems off. Read-only: it never creates a store,
- * installs a hook or migrates a database. Every non-passing check names the
- * command that fixes it, so an agent can act on the `--json` output.
- */
+/** `hippo doctor`: a read-only health check (never creates a store, installs a hook or migrates a database).
+ * Every non-passing check names the command that fixes it, so an agent can act on the `--json` output. */
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { findHippoStoreDir } from './core/project-identity.js';
-import { getGlobalRoot } from './sharing/shared.js';
+import { getGlobalRoot } from './sharing/global-store.js';
 import { isInitialized } from './store/open.js';
 import { readStoreHealth } from './store/diagnostics.js';
 import { loadConfig } from './core/config.js';
@@ -50,7 +46,12 @@ function codexCheck(home) {
     const parsed = readJson(file);
     // Codex drops every hook in a hooks.json it cannot parse, hippo's included.
     if (fs.existsSync(file) && !isJsonObjectLiteral(parsed)) {
-        return { id: 'codex', status: 'warn', detail: "Codex's hooks.json is not a JSON object, so Codex runs no hook from it", fix: 'repair hooks.json, then run: hippo hook install codex' };
+        return {
+            id: 'codex',
+            status: 'warn',
+            detail: "Codex's hooks.json is not a JSON object, so Codex runs no hook from it",
+            fix: 'repair hooks.json, then run: hippo hook install codex'
+        };
     }
     const text = JSON.stringify(parsed ?? '');
     const codexHooks = [
@@ -63,7 +64,9 @@ function codexCheck(home) {
     return {
         id: 'codex',
         status: 'warn',
-        detail: missing.length === codexHooks.length ? "Codex found, but hippo's memory hooks are not installed" : `Codex: hippo hooks missing for ${missing.join(', ')}`,
+        detail: missing.length === codexHooks.length
+            ? "Codex found, but hippo's memory hooks are not installed"
+            : `Codex: hippo hooks missing for ${missing.join(', ')}`,
         fix: 'hippo hook install codex   (then trust the hooks once in /hooks)',
     };
 }
@@ -88,7 +91,12 @@ function sleepCheck(lastSleep, now) {
     const last = lastSleep.value;
     const when = last !== undefined ? Date.parse(last) : Number.NaN;
     if (Number.isNaN(when)) {
-        return { id: 'sleep', status: 'warn', detail: 'hippo has never slept (consolidated) in this store', fix: 'hippo sleep   (the session-end hook runs it automatically)' };
+        return {
+            id: 'sleep',
+            status: 'warn',
+            detail: 'hippo has never slept (consolidated) in this store',
+            fix: 'hippo sleep   (the session-end hook runs it automatically)'
+        };
     }
     const days = Math.floor((now.getTime() - when) / DAY_MS);
     return days > 7
@@ -137,12 +145,19 @@ function projectsCheck(globalRoot) {
         const found = [
             r.copies.length > 0 ? `${r.copies.length} imported notes copied under the wrong project` : '',
             r.folds.length > 0 ? `old project names that now resolve to another project: ${r.folds.map((f) => `${f.from} -> ${f.into}`).join(', ')}` : '',
-            r.collisions.length > 0 ? `old project names shared by several projects, folded by hand only: ${r.collisions.map((c) => `${c.name} (${c.ids.join(', ')})`).join('; ')}` : '',
+            r.collisions.length > 0
+                ? `old project names shared by several projects, folded by hand only: ${r.collisions.map((c) => `${c.name} (${c.ids.join(', ')})`).join('; ')}`
+                : '',
             r.toProject.length + r.setAside.length > 0 ? `${r.toProject.length + r.setAside.length} merged memories tagged user-global` : '',
         ].filter((s) => s !== '');
         return found.length === 0
             ? { id: 'projects', status: 'pass', detail: 'no duplicate or out-of-date project tags in the global store' }
-            : { id: 'projects', status: 'warn', detail: `global store: ${found.join('; ')}`, fix: 'hippo projects repair --global   (dry run; add --apply to write)' };
+            : {
+                id: 'projects',
+                status: 'warn',
+                detail: `global store: ${found.join('; ')}`,
+                fix: 'hippo projects repair --global   (dry run; add --apply to write)'
+            };
     }
     catch (err) {
         return { id: 'projects', status: 'info', detail: `project tags not checked (${errorMessage(err)})` };
@@ -160,16 +175,43 @@ function nodeCheck(node) {
 /** The store the checks run against (project first, then global), and the check that says which. */
 function storeCheck(local, globalRoot, hasGlobal) {
     if (local !== null && isInitialized(local)) {
-        return { store: local, check: { id: 'store', status: 'pass', detail: `project store at ${local}${hasGlobal ? ` (global store at ${globalRoot} too)` : ''}` } };
+        return {
+            store: local,
+            check: { id: 'store', status: 'pass', detail: `project store at ${local}${hasGlobal ? ` (global store at ${globalRoot} too)` : ''}` }
+        };
     }
     if (local !== null) {
         // The walk stops at the first .hippo it finds, so a bare one (no hippo.db) blocks a parent or global store too.
-        return { store: null, check: { id: 'store', status: 'fail', detail: `${local} has no hippo.db, so hippo commands run here stop at it`, fix: `run hippo init in ${path.dirname(local)}, or remove that .hippo folder` } };
+        return {
+            store: null,
+            check: {
+                id: 'store',
+                status: 'fail',
+                detail: `${local} has no hippo.db, so hippo commands run here stop at it`,
+                fix: `run hippo init in ${path.dirname(local)}, or remove that .hippo folder`
+            }
+        };
     }
     if (hasGlobal) {
-        return { store: globalRoot, check: { id: 'store', status: 'warn', detail: `no project store here; using the global store at ${globalRoot}`, fix: 'hippo init   (in the project root)' } };
+        return {
+            store: globalRoot,
+            check: {
+                id: 'store',
+                status: 'warn',
+                detail: `no project store here; using the global store at ${globalRoot}`,
+                fix: 'hippo init   (in the project root)'
+            }
+        };
     }
-    return { store: null, check: { id: 'store', status: 'fail', detail: 'no hippo store found (project or global)', fix: 'hippo init   (in the project root), or hippo init --global' } };
+    return {
+        store: null,
+        check: {
+            id: 'store',
+            status: 'fail',
+            detail: 'no hippo store found (project or global)',
+            fix: 'hippo init   (in the project root), or hippo init --global'
+        }
+    };
 }
 function schemaCheck(have, want) {
     return have === want
@@ -269,7 +311,12 @@ function claudeCodeCheck(home) {
     if (missing.length === CLAUDE_CODE_HOOKS.length) {
         return { id: 'claude-code', status: 'warn', detail: 'Claude Code found, but no hippo hooks are installed', fix: 'hippo hook install claude-code' };
     }
-    return { id: 'claude-code', status: 'warn', detail: `Claude Code: hippo hooks missing for ${missing.join(', ')}`, fix: 'hippo hook install claude-code   (adds only what is missing)' };
+    return {
+        id: 'claude-code',
+        status: 'warn',
+        detail: `Claude Code: hippo hooks missing for ${missing.join(', ')}`,
+        fix: 'hippo hook install claude-code   (adds only what is missing)'
+    };
 }
 /** Run every check. Never throws for a broken install; broken parts become failed checks. */
 export function runDoctor(opts) {
@@ -287,14 +334,22 @@ export function runDoctor(opts) {
         checks.push(...databaseChecks(store, now));
     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})` });
+        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));
     checks.push(claudeCodeCheck(home));
     if (isCodexPresent(home))
         checks.push(codexCheck(home));
-    checks.push({ id: 'embeddings', status: 'info', detail: isEmbeddingAvailable() ? 'local embeddings available (hybrid search)' : 'embeddings not installed; recall uses BM25 (optional: hippo embed --help)' });
+    checks.push({
+        id: 'embeddings',
+        status: 'info',
+        detail: isEmbeddingAvailable() ? 'local embeddings available (hybrid search)' : 'embeddings not installed; recall uses BM25 (optional: hippo embed --help)'
+    });
     return { ok: !checks.some((c) => c.status === 'fail'), version: opts.version, store, checks };
 }
 /** Human-readable rendering of a {@link DoctorReport}. */

package/dist/entry/session-text.js

@@ -1,4 +1,5 @@
-// The hippo-memory/session-text subpath: what a hook reads from a session (turns, working state, failures, git state, compaction items) and the sharing scrub, with no store, database or server in its imports.
+// The hippo-memory/session-text subpath: what a hook reads from a session (turns, working state, failures,
+// git state, compaction items) and the sharing scrub, with no store, database or server in its imports.
 export { collectSessionTurns, sessionTail } from '../capture/transcript.js';
 export { scrubForSharing } from '../capture/share-scrub.js';
 export { transcriptWorkingState, WORKING_STATE_CAPS } from '../capture/working-state.js';

package/dist/eval/eval-stats.d.ts

@@ -1,16 +1,5 @@
-/**
- * Statistics and cost accounting for the token-efficiency evals.
- *
- * - Cost: price provider usage over four buckets (uncached input, cache
- *   write, cache read, output). Raw token counts overstate savings when most
- *   input is already cache reads, so every dollar claim goes through here.
- * - Uncertainty: paired bootstrap over tasks, cluster bootstrap (tasks that
- *   share a repository are not independent), and a paired ratio bootstrap for
- *   dollars per resolved task.
- *
- * Deterministic: every resampling function takes a seed, so a published
- * result can be reproduced exactly.
- */
+/** Statistics and cost accounting for the token-efficiency evals: cost is priced over four buckets (uncached input, cache write, cache read, output).
+ *  Uncertainty uses paired, cluster (same-repository tasks are not independent) and paired-ratio bootstraps; every resampler takes a seed. */
 /** Token usage for one model call or one whole task, split by how it is billed. */
 export interface Usage {
     /** Input tokens billed at the base input price (not read from or written to a cache). */
@@ -22,11 +11,7 @@ export interface Usage {
     /** Output tokens, including any reasoning tokens the provider bills as output. */
     outputTokens: number;
 }
-/**
- * Prices in dollars per million tokens. Take them from the provider's
- * current price page for the exact model; this module has no built-in
- * prices because they change.
- */
+/** Prices in dollars per million tokens, taken from the provider's current price page for the exact model; this module has no built-in prices. */
 export interface Prices {
     inputPerMTok: number;
     cacheWritePerMTok: number;
@@ -37,12 +22,8 @@ export interface Prices {
 export declare function addUsage(...usages: Usage[]): Usage;
 /** Dollar cost of `usage` at `prices`. */
 export declare function priceUsage(usage: Usage, prices: Prices): number;
-/**
- * Relative prices of the cache buckets against the base input price, for
- * cost in "uncached-equivalent tokens" when no dollar prices are given.
- * Defaults follow Anthropic's published ratios (5-minute cache write 1.25x,
- * cache read 0.1x); pass the ratios for another provider when needed.
- */
+/** Relative cache-bucket prices against the base input price, for cost in "uncached-equivalent tokens" when no dollar prices are given.
+ *  Defaults follow Anthropic's ratios (5-minute cache write 1.25x, cache read 0.1x); pass another provider's ratios when needed. */
 export interface CacheRatios {
     write: number;
     read: number;
@@ -51,10 +32,8 @@ export interface CacheRatios {
 export declare const DEFAULT_CACHE_RATIOS: Readonly<CacheRatios>;
 /** Input cost of `usage` in uncached-equivalent tokens (output excluded). */
 export declare function uncachedEquivalentInput(usage: Usage, ratios?: CacheRatios): number;
-/**
- * Mulberry32: a small seeded PRNG returning floats in [0, 1). Same seed,
- * same stream, on every platform.
- */
+/** Mulberry32: a small seeded PRNG returning floats in [0, 1). Same seed,
+ *  same stream, on every platform. */
 export declare function seededRandom(seed: number): () => number;
 /** A point estimate with a percentile bootstrap confidence interval. */
 export interface Estimate {
@@ -73,17 +52,9 @@ export interface BootstrapOpts {
     /** PRNG seed. Default 1. */
     seed?: number;
 }
-/**
- * Paired bootstrap for the mean of per-task differences (treatment minus
- * control on the same task). An interval that excludes zero is the bar for
- * calling a difference real.
- */
+/** Paired bootstrap for the mean of per-task differences (treatment minus control, same task); an interval excluding zero is the bar for a real difference. */
 export declare function pairedBootstrap(diffs: number[], opts?: BootstrapOpts): Estimate;
-/**
- * Cluster bootstrap for the mean of per-task differences: resamples whole
- * clusters (for example all tasks from one repository), because tasks in a
- * cluster share causes and are not independent draws.
- */
+/** Cluster bootstrap for the mean of per-task differences: resamples whole clusters (e.g. one repository), because tasks in a cluster are not independent. */
 export declare function clusteredPairedBootstrap(diffsByCluster: ReadonlyMap<string, number[]>, opts?: BootstrapOpts): Estimate;
 /** One task's outcome in one arm, for {@link costPerResolvedDelta}. */
 export interface ArmOutcome {
@@ -101,23 +72,14 @@ export interface CostPerResolvedDelta {
     /** (treatment minus control) / control, with its interval. Negative is a saving. */
     relative: Estimate;
 }
-/**
- * Cost per resolved task in two arms run on the same tasks, with a paired
- * bootstrap over tasks (a task is resampled with both of its arm outcomes).
- * `control[i]` and `treatment[i]` must be the same task. Resamples in which
- * an arm resolves nothing are dropped; `iterations` reports how many were
- * kept.
- */
+/** Cost per resolved task in two arms on the same tasks, with a paired bootstrap (`control[i]` and `treatment[i]` must be the same task).
+ *  Resamples in which an arm resolves nothing are dropped; `iterations` reports how many were kept. */
 export declare function costPerResolvedDelta(control: ArmOutcome[], treatment: ArmOutcome[], opts?: BootstrapOpts): CostPerResolvedDelta;
-/**
- * pass@k: share of tasks with at least one success in their first k runs.
- * NaN when no task has k runs (not measured, which is not the same as 0).
- */
+/** pass@k: share of tasks with at least one success in their first k runs.
+ *  NaN when no task has k runs (not measured, which is not the same as 0). */
 export declare function passAtK(runsByTask: boolean[][], k: number): number;
-/**
- * pass^k: share of tasks whose first k runs all succeed (consistency).
- * NaN when no task has k runs.
- */
+/** pass^k: share of tasks whose first k runs all succeed (consistency).
+ *  NaN when no task has k runs. */
 export declare function passHatK(runsByTask: boolean[][], k: number): number;
 /** All units of one family (tasks by seeds), resampled as one block so seeds stay together. */
 export type Family<T> = readonly T[];

package/dist/eval/eval-stats.js

@@ -1,16 +1,5 @@
-/**
- * Statistics and cost accounting for the token-efficiency evals.
- *
- * - Cost: price provider usage over four buckets (uncached input, cache
- *   write, cache read, output). Raw token counts overstate savings when most
- *   input is already cache reads, so every dollar claim goes through here.
- * - Uncertainty: paired bootstrap over tasks, cluster bootstrap (tasks that
- *   share a repository are not independent), and a paired ratio bootstrap for
- *   dollars per resolved task.
- *
- * Deterministic: every resampling function takes a seed, so a published
- * result can be reproduced exactly.
- */
+/** Statistics and cost accounting for the token-efficiency evals: cost is priced over four buckets (uncached input, cache write, cache read, output).
+ *  Uncertainty uses paired, cluster (same-repository tasks are not independent) and paired-ratio bootstraps; every resampler takes a seed. */
 const DEFAULT_ITERATIONS = 5000;
 const DEFAULT_TWO_LEVEL_ITERATIONS = 10_000;
 const DEFAULT_ALPHA = 0.05;
@@ -38,10 +27,8 @@ export const DEFAULT_CACHE_RATIOS = { write: 1.25, read: 0.1 };
 export function uncachedEquivalentInput(usage, ratios = DEFAULT_CACHE_RATIOS) {
     return usage.inputTokens + usage.cacheWriteTokens * ratios.write + usage.cacheReadTokens * ratios.read;
 }
-/**
- * Mulberry32: a small seeded PRNG returning floats in [0, 1). Same seed,
- * same stream, on every platform.
- */
+/** Mulberry32: a small seeded PRNG returning floats in [0, 1). Same seed,
+ *  same stream, on every platform. */
 export function seededRandom(seed) {
     let a = seed >>> 0;
     return () => {
@@ -61,11 +48,7 @@ function percentileInterval(samples, alpha) {
 function mean(xs) {
     return xs.length === 0 ? 0 : xs.reduce((s, x) => s + x, 0) / xs.length;
 }
-/**
- * Paired bootstrap for the mean of per-task differences (treatment minus
- * control on the same task). An interval that excludes zero is the bar for
- * calling a difference real.
- */
+/** Paired bootstrap for the mean of per-task differences (treatment minus control, same task); an interval excluding zero is the bar for a real difference. */
 export function pairedBootstrap(diffs, opts = {}) {
     const iterations = opts.iterations ?? DEFAULT_ITERATIONS;
     const alpha = opts.alpha ?? DEFAULT_ALPHA;
@@ -82,11 +65,7 @@ export function pairedBootstrap(diffs, opts = {}) {
     }
     return { estimate: mean(diffs), ...percentileInterval(samples, alpha), iterations };
 }
-/**
- * Cluster bootstrap for the mean of per-task differences: resamples whole
- * clusters (for example all tasks from one repository), because tasks in a
- * cluster share causes and are not independent draws.
- */
+/** Cluster bootstrap for the mean of per-task differences: resamples whole clusters (e.g. one repository), because tasks in a cluster are not independent. */
 export function clusteredPairedBootstrap(diffsByCluster, opts = {}) {
     const iterations = opts.iterations ?? DEFAULT_ITERATIONS;
     const alpha = opts.alpha ?? DEFAULT_ALPHA;
@@ -115,13 +94,8 @@ function costPerResolved(outcomes) {
     const cost = outcomes.reduce((s, o) => s + o.cost, 0);
     return resolved === 0 ? Number.POSITIVE_INFINITY : cost / resolved;
 }
-/**
- * Cost per resolved task in two arms run on the same tasks, with a paired
- * bootstrap over tasks (a task is resampled with both of its arm outcomes).
- * `control[i]` and `treatment[i]` must be the same task. Resamples in which
- * an arm resolves nothing are dropped; `iterations` reports how many were
- * kept.
- */
+/** Cost per resolved task in two arms on the same tasks, with a paired bootstrap (`control[i]` and `treatment[i]` must be the same task).
+ *  Resamples in which an arm resolves nothing are dropped; `iterations` reports how many were kept. */
 export function costPerResolvedDelta(control, treatment, opts = {}) {
     if (control.length !== treatment.length) {
         throw new Error('control and treatment must list the same tasks in the same order');
@@ -166,20 +140,16 @@ export function costPerResolvedDelta(control, treatment, opts = {}) {
         },
     };
 }
-/**
- * pass@k: share of tasks with at least one success in their first k runs.
- * NaN when no task has k runs (not measured, which is not the same as 0).
- */
+/** pass@k: share of tasks with at least one success in their first k runs.
+ *  NaN when no task has k runs (not measured, which is not the same as 0). */
 export function passAtK(runsByTask, k) {
     const eligible = runsByTask.filter((r) => r.length >= k);
     if (eligible.length === 0)
         return Number.NaN;
     return eligible.filter((r) => r.slice(0, k).some(Boolean)).length / eligible.length;
 }
-/**
- * pass^k: share of tasks whose first k runs all succeed (consistency).
- * NaN when no task has k runs.
- */
+/** pass^k: share of tasks whose first k runs all succeed (consistency).
+ *  NaN when no task has k runs. */
 export function passHatK(runsByTask, k) {
     const eligible = runsByTask.filter((r) => r.length >= k);
     if (eligible.length === 0)

package/dist/eval/eval-suite.d.ts

@@ -1,16 +1,5 @@
-/**
- * Self-contained feature evaluation suite for hippo.
- *
- * Creates a synthetic memory corpus with known ground truth, runs searches
- * per feature category, and reports per-feature metrics with regression
- * detection against a saved baseline.
- *
- * Design goals:
- *  - Zero API calls (no LLM judge, no embeddings)
- *  - Deterministic (fixed timestamps, content, IDs)
- *  - Fast (<60s for full suite)
- *  - Per-feature breakdown so you see exactly what a change helped/hurt
- */
+/** Self-contained feature eval suite: a synthetic corpus with known ground truth, per-feature metrics and regression detection against a saved baseline.
+ *  Zero API calls (no LLM judge, no embeddings), deterministic (fixed timestamps, content, IDs) and fast. */
 import { type MemoryEntry } from '../core/memory.js';
 export type FeatureCategory = 'direct-recall' | 'extraction-preference' | 'dag-drilldown' | 'temporal' | 'noise-resistance' | 'multi-hop';
 export interface FeatureTestCase {