hippo-memory 0.36.0 → 0.37.0

package/dist/src/embeddings.js

@@ -0,0 +1,344 @@
+/**
+ * Optional embedding-based semantic search for Hippo.
+ * Uses @xenova/transformers (local, zero API keys, ~22MB model).
+ * Falls back silently if the library is not installed.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { createRequire } from 'module';
+import { loadAllEntries } from './store.js';
+import { openHippoDb, closeHippoDb, getMeta, setMeta } from './db.js';
+import { initializeParticle, savePhysicsState, loadPhysicsState, resetAllPhysicsState } from './physics-state.js';
+import { loadConfig } from './config.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();
+const DEFAULT_EMBEDDING_MODEL = 'Xenova/all-MiniLM-L6-v2';
+const EMBEDDING_MODEL_META_KEY = 'embedding_model';
+// Use Function constructor to bypass TypeScript static module resolution
+// for optional peer dependencies that may not be installed.
+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;
+}
+// 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
+        let pipelineFn = null;
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const mod = await _dynImport('@xenova/transformers');
+            pipelineFn = mod.pipeline ?? mod.default?.pipeline;
+        }
+        catch {
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const mod = await _dynImport('@huggingface/transformers');
+                pipelineFn = mod.pipeline ?? mod.default?.pipeline;
+            }
+            catch {
+                return null;
+            }
+        }
+        if (!pipelineFn)
+            return null;
+        try {
+            const instance = await pipelineFn('feature-extraction', model, { quantized: true });
+            _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);
+        try {
+            const model = getMeta(db, EMBEDDING_MODEL_META_KEY, '').trim();
+            return model || null;
+        }
+        finally {
+            closeHippoDb(db);
+        }
+    }
+    catch {
+        return null;
+    }
+}
+function saveStoredEmbeddingModel(hippoRoot, model) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        setMeta(db, EMBEDDING_MODEL_META_KEY, model);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+export function resolveIndexedEmbeddingModel(hippoRoot, index = loadEmbeddingIndex(hippoRoot)) {
+    const stored = loadStoredEmbeddingModel(hippoRoot);
+    if (stored)
+        return stored;
+    return Object.keys(index).length > 0 ? DEFAULT_EMBEDDING_MODEL : null;
+}
+export function embeddingModelRequiresReindex(hippoRoot, model, index = loadEmbeddingIndex(hippoRoot)) {
+    const indexedModel = resolveIndexedEmbeddingModel(hippoRoot, index);
+    return indexedModel !== null && indexedModel !== model;
+}
+async function rebuildEmbeddingIndex(entries, model) {
+    const rebuilt = {};
+    for (const entry of entries) {
+        const text = `${entry.content} ${entry.tags.join(' ')}`.trim();
+        const vector = await getEmbedding(text, model);
+        if (vector.length > 0) {
+            rebuilt[entry.id] = vector;
+        }
+    }
+    return rebuilt;
+}
+function resetPhysicsFromIndex(hippoRoot, entries, index) {
+    try {
+        const db = openHippoDb(hippoRoot);
+        try {
+            resetAllPhysicsState(db, entries, index);
+        }
+        finally {
+            closeHippoDb(db);
+        }
+    }
+    catch {
+        // Physics reset is best-effort; retrieval will still fall back gracefully.
+    }
+}
+/**
+ * Get an embedding vector for a piece of text.
+ * Returns an empty array if transformers is not available or fails.
+ */
+export async function getEmbedding(text, model = DEFAULT_EMBEDDING_MODEL) {
+    if (!isEmbeddingAvailable())
+        return [];
+    try {
+        const pipe = await loadPipeline(model);
+        if (!pipe)
+            return [];
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const output = await pipe(text, { pooling: 'mean', normalize: true });
+        return Array.from(output.data);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Cosine similarity between two vectors. Handles unnormalized vectors.
+ * Returns 0 for empty or mismatched vectors.
+ */
+export function cosineSimilarity(a, b) {
+    if (a.length === 0 || b.length === 0 || a.length !== b.length)
+        return 0;
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    if (denom < 1e-10)
+        return 0;
+    // Clamp to [-1, 1] to handle floating point drift
+    return Math.min(1, Math.max(-1, dot / denom));
+}
+const EMBEDDINGS_FILE = 'embeddings.json';
+/**
+ * Load the cached embedding index from disk.
+ * Returns an empty object if the file doesn't exist or is corrupt.
+ */
+export function loadEmbeddingIndex(hippoRoot) {
+    const fp = path.join(hippoRoot, EMBEDDINGS_FILE);
+    if (!fs.existsSync(fp))
+        return {};
+    try {
+        return JSON.parse(fs.readFileSync(fp, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * 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;
+    }
+}
+// Mutex to serialize embedding writes and prevent read-modify-write races
+let _embedWriteLock = Promise.resolve();
+async function withEmbedLock(fn) {
+    let resolve;
+    const next = new Promise(r => { resolve = r; });
+    const prev = _embedWriteLock;
+    _embedWriteLock = next;
+    await prev;
+    try {
+        return await fn();
+    }
+    finally {
+        resolve();
+    }
+}
+/**
+ * Embed a single memory entry and cache the result in the embedding index.
+ */
+export async function embedMemory(hippoRoot, entry, model) {
+    if (!isEmbeddingAvailable())
+        return;
+    return withEmbedLock(async () => {
+        const effectiveModel = resolveEmbeddingModel(hippoRoot, model);
+        const existingIndex = loadEmbeddingIndex(hippoRoot);
+        if (embeddingModelRequiresReindex(hippoRoot, effectiveModel, existingIndex)) {
+            const entries = loadAllEntries(hippoRoot);
+            const rebuiltIndex = await rebuildEmbeddingIndex(entries, effectiveModel);
+            saveEmbeddingIndex(hippoRoot, rebuiltIndex);
+            saveStoredEmbeddingModel(hippoRoot, effectiveModel);
+            resetPhysicsFromIndex(hippoRoot, entries, rebuiltIndex);
+            return;
+        }
+        const text = `${entry.content} ${entry.tags.join(' ')}`.trim();
+        const vector = await getEmbedding(text, effectiveModel);
+        if (vector.length === 0)
+            return;
+        const index = existingIndex;
+        index[entry.id] = vector;
+        saveEmbeddingIndex(hippoRoot, index);
+        saveStoredEmbeddingModel(hippoRoot, effectiveModel);
+        // Initialize physics state for this memory
+        try {
+            const db = openHippoDb(hippoRoot);
+            try {
+                const existing = loadPhysicsState(db, [entry.id]);
+                if (!existing.has(entry.id)) {
+                    const particle = initializeParticle(entry, vector);
+                    savePhysicsState(db, [particle]);
+                }
+            }
+            finally {
+                closeHippoDb(db);
+            }
+        }
+        catch {
+            // Physics init is best-effort — don't break embedding
+        }
+    });
+}
+/**
+ * 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.
+ */
+export async function embedAll(hippoRoot, model) {
+    if (!isEmbeddingAvailable())
+        return 0;
+    return withEmbedLock(async () => {
+        const effectiveModel = resolveEmbeddingModel(hippoRoot, model);
+        const entries = loadAllEntries(hippoRoot);
+        const index = loadEmbeddingIndex(hippoRoot);
+        if (embeddingModelRequiresReindex(hippoRoot, effectiveModel, index)) {
+            const rebuiltIndex = await rebuildEmbeddingIndex(entries, effectiveModel);
+            saveEmbeddingIndex(hippoRoot, rebuiltIndex);
+            saveStoredEmbeddingModel(hippoRoot, effectiveModel);
+            resetPhysicsFromIndex(hippoRoot, entries, rebuiltIndex);
+            return Object.keys(rebuiltIndex).length;
+        }
+        let count = 0;
+        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;
+            }
+        }
+        for (const entry of entries) {
+            if (index[entry.id])
+                continue; // already embedded
+            const text = `${entry.content} ${entry.tags.join(' ')}`.trim();
+            const vector = await getEmbedding(text, effectiveModel);
+            if (vector.length > 0) {
+                index[entry.id] = vector;
+                count++;
+                dirty = true;
+            }
+        }
+        if (dirty) {
+            saveEmbeddingIndex(hippoRoot, index);
+        }
+        saveStoredEmbeddingModel(hippoRoot, effectiveModel);
+        return count;
+    });
+}
+//# sourceMappingURL=embeddings.js.map

package/dist/src/embeddings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embeddings.js","sourceRoot":"","sources":["../../src/embeddings.ts"],"names":[],"mappings":"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"}

package/dist/src/eval-suite.js

@@ -0,0 +1,289 @@
+/**
+ * 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
+ */
+import { createMemory, Layer } from './memory.js';
+import { search } from './search.js';
+import { multihopSearch } from './multihop.js';
+import { mrr, recallAtK, ndcgAtK } from './eval.js';
+// ---------------------------------------------------------------------------
+// Synthetic corpus — deterministic, no API calls
+// ---------------------------------------------------------------------------
+const BASE_DATE = new Date('2026-01-15T10:00:00Z');
+function dateOffset(days) {
+    const d = new Date(BASE_DATE.getTime() + days * 86400000);
+    return d.toISOString();
+}
+function mem(id, content, opts = {}) {
+    const entry = createMemory(content, {
+        layer: opts.layer ?? Layer.Episodic,
+        tags: opts.tags ?? [],
+        baseHalfLifeDays: 30,
+        extracted_from: opts.extracted_from,
+        dag_level: opts.dag_level,
+        dag_parent_id: opts.dag_parent_id,
+    });
+    entry.id = id;
+    if (opts.created)
+        entry.created = opts.created;
+    return entry;
+}
+export function buildSyntheticCorpus() {
+    const entries = [];
+    const cases = [];
+    // =========================================================================
+    // 1. DIRECT RECALL — basic keyword matching
+    // =========================================================================
+    entries.push(mem('dr-1', 'The PostgreSQL database migration failed because the users table had a NOT NULL constraint on the email column', { created: dateOffset(1), tags: ['topic:database'] }), mem('dr-2', 'React component rendering performance improved by 40% after memoizing the expensive computation in useMemo', { created: dateOffset(2), tags: ['topic:frontend'] }), mem('dr-3', 'The API rate limiter should use a sliding window algorithm instead of fixed window to prevent burst traffic', { created: dateOffset(3), tags: ['topic:api'] }), mem('dr-4', 'Docker container memory limits need to be set to 512MB for the worker service to prevent OOM kills', { created: dateOffset(4), tags: ['topic:devops'] }), mem('dr-5', 'The JWT token expiration was set to 24 hours but should be reduced to 1 hour for security compliance', { created: dateOffset(5), tags: ['topic:security'] }), mem('dr-6', 'Webpack bundle size grew to 2.3MB because lodash was imported as a whole instead of cherry-picking', { created: dateOffset(6), tags: ['topic:frontend'] }), mem('dr-7', 'The Redis cache TTL for user sessions should match the JWT expiration to prevent stale sessions', { created: dateOffset(7), tags: ['topic:caching'] }), mem('dr-8', 'GraphQL resolver for nested comments has N+1 query problem solved by DataLoader batching', { created: dateOffset(8), tags: ['topic:api'] }));
+    cases.push({ id: 'dr-q1', category: 'direct-recall', query: 'PostgreSQL migration NOT NULL constraint', expectedIds: ['dr-1'], description: 'exact keyword match on DB migration' }, { id: 'dr-q2', category: 'direct-recall', query: 'React useMemo performance memoizing', expectedIds: ['dr-2'], description: 'React performance optimization' }, { id: 'dr-q3', category: 'direct-recall', query: 'sliding window rate limiter API', expectedIds: ['dr-3'], description: 'API rate limiting approach' }, { id: 'dr-q4', category: 'direct-recall', query: 'Docker OOM memory limits worker', expectedIds: ['dr-4'], description: 'Docker memory config' }, { id: 'dr-q5', category: 'direct-recall', query: 'JWT token expiration security', expectedIds: ['dr-5'], description: 'JWT security setting' }, { id: 'dr-q6', category: 'direct-recall', query: 'webpack bundle size lodash', expectedIds: ['dr-6'], description: 'bundle size issue' }, { id: 'dr-q7', category: 'direct-recall', query: 'Redis cache TTL session expiration', expectedIds: ['dr-7'], description: 'cache TTL config' }, { id: 'dr-q8', category: 'direct-recall', query: 'GraphQL N+1 DataLoader batching', expectedIds: ['dr-8'], description: 'GraphQL N+1 fix' });
+    // =========================================================================
+    // 2. EXTRACTION PREFERENCE — extracted facts should rank above raw source
+    // =========================================================================
+    entries.push(mem('ep-src-1', 'speaker:Alice: So we had this big meeting yesterday about the deployment pipeline and Bob mentioned that the staging environment is using Kubernetes 1.28 and we should upgrade to 1.30 before the end of Q2 because of the security patches', {
+        created: dateOffset(10), tags: ['speaker:Alice', 'topic:infrastructure', 'session:meeting-1'],
+    }), mem('ep-ext-1', 'The staging environment runs Kubernetes 1.28 and needs to be upgraded to 1.30 before end of Q2 for security patches', {
+        created: dateOffset(10), layer: Layer.Semantic, tags: ['speaker:Alice', 'topic:infrastructure', 'extracted'],
+        extracted_from: 'ep-src-1',
+    }), mem('ep-src-2', 'speaker:Bob: Yeah and the thing about the monitoring is that we switched from Datadog to Grafana last month and the alerting rules still need to be migrated, Carol was supposed to handle that but she has been busy with the frontend rewrite', {
+        created: dateOffset(11), tags: ['speaker:Bob', 'topic:monitoring', 'session:meeting-1'],
+    }), mem('ep-ext-2', 'The team switched from Datadog to Grafana last month but alerting rules have not been migrated yet. Carol is responsible but blocked by the frontend rewrite.', {
+        created: dateOffset(11), layer: Layer.Semantic, tags: ['speaker:Bob', 'topic:monitoring', 'extracted'],
+        extracted_from: 'ep-src-2',
+    }), mem('ep-src-3', 'speaker:Carol: The login page redesign is almost done, I just need to wire up the OAuth2 PKCE flow with the new identity provider and write the integration tests', {
+        created: dateOffset(12), tags: ['speaker:Carol', 'topic:auth', 'session:meeting-2'],
+    }), mem('ep-ext-3', 'Carol is nearly done with the login page redesign. Remaining work: wire up OAuth2 PKCE flow with the new identity provider and write integration tests.', {
+        created: dateOffset(12), layer: Layer.Semantic, tags: ['speaker:Carol', 'topic:auth', 'extracted'],
+        extracted_from: 'ep-src-3',
+    }));
+    cases.push({ id: 'ep-q1', category: 'extraction-preference', query: 'Kubernetes upgrade staging environment', expectedIds: ['ep-ext-1'], description: 'extracted fact about K8s upgrade should rank above raw utterance' }, { id: 'ep-q2', category: 'extraction-preference', query: 'Datadog Grafana alerting migration', expectedIds: ['ep-ext-2'], description: 'extracted fact about monitoring switch' }, { id: 'ep-q3', category: 'extraction-preference', query: 'OAuth2 PKCE login page redesign', expectedIds: ['ep-ext-3'], description: 'extracted fact about auth work' });
+    // =========================================================================
+    // 3. DAG DRILL-DOWN — summary nodes should surface children
+    // =========================================================================
+    entries.push(mem('dag-child-1', 'The API response time for /users endpoint degraded from 50ms to 300ms after adding the permissions check', {
+        created: dateOffset(15), layer: Layer.Semantic, tags: ['topic:api-performance', 'extracted'],
+        dag_level: 1,
+    }), mem('dag-child-2', 'The /orders endpoint latency spiked to 500ms because of a missing index on the orders.created_at column', {
+        created: dateOffset(15), layer: Layer.Semantic, tags: ['topic:api-performance', 'extracted'],
+        dag_level: 1,
+    }), mem('dag-child-3', 'Batch API endpoint /reports/generate takes 8 seconds because it runs synchronously instead of using a job queue', {
+        created: dateOffset(15), layer: Layer.Semantic, tags: ['topic:api-performance', 'extracted'],
+        dag_level: 1,
+    }), mem('dag-summary-1', 'API performance issues: /users degraded to 300ms (permissions check), /orders spiked to 500ms (missing index), /reports takes 8s (needs job queue)', {
+        created: dateOffset(16), layer: Layer.Semantic, tags: ['topic:api-performance'],
+        dag_level: 2, dag_parent_id: undefined,
+    }));
+    // Link children to parent
+    for (const child of [entries.find(e => e.id === 'dag-child-1'), entries.find(e => e.id === 'dag-child-2'), entries.find(e => e.id === 'dag-child-3')]) {
+        child.dag_parent_id = 'dag-summary-1';
+    }
+    cases.push({ id: 'dag-q1', category: 'dag-drilldown', query: 'API performance problems latency', expectedIds: ['dag-child-1', 'dag-child-2', 'dag-child-3', 'dag-summary-1'], description: 'summary should drill down to all children' }, { id: 'dag-q2', category: 'dag-drilldown', query: 'endpoint response time degradation', expectedIds: ['dag-child-1', 'dag-child-2', 'dag-summary-1'], description: 'query matching summary should surface relevant children' });
+    // =========================================================================
+    // 4. TEMPORAL — recency/oldest cues should affect ranking
+    // =========================================================================
+    entries.push(mem('tmp-1', 'The team decided to use TypeScript for the new service', { created: dateOffset(-30), tags: ['topic:architecture'] }), mem('tmp-2', 'The team evaluated Rust as an alternative language for the service', { created: dateOffset(-20), tags: ['topic:architecture'] }), mem('tmp-3', 'The team added Go as a candidate language for the service rewrite', { created: dateOffset(-10), tags: ['topic:architecture'] }), mem('tmp-4', 'The team finalized the language choice as Go for the service rewrite', { created: dateOffset(-1), tags: ['topic:architecture'] }));
+    cases.push({ id: 'tmp-q1', category: 'temporal', query: 'what did the team recently decide about the service language', expectedIds: ['tmp-4'], description: 'recent cue should boost newest entry' }, { id: 'tmp-q2', category: 'temporal', query: 'what was the first language choice for the service', expectedIds: ['tmp-1'], description: 'oldest cue should boost earliest entry' }, { id: 'tmp-q3', category: 'temporal', query: 'latest update on the service rewrite language', expectedIds: ['tmp-4'], description: 'latest should boost most recent' }, { id: 'tmp-q4', category: 'temporal', query: 'original architecture decision for the service', expectedIds: ['tmp-1'], description: 'original should boost earliest' });
+    // =========================================================================
+    // 5. NOISE RESISTANCE — relevant memories found despite noise
+    // =========================================================================
+    // Add 30 noise entries
+    const noiseTopics = [
+        'breakfast meeting catering ordered sandwiches', 'office temperature thermostat adjusted',
+        'printer paper refill third floor supply', 'parking lot gate code changed 4521',
+        'fire drill scheduled next Thursday morning', 'coffee machine broken maintenance called',
+        'desk booking system new policy hybrid', 'meeting room projector HDMI adapter missing',
+        'birthday celebration for Dave next Friday', 'recycling bins moved to kitchen area',
+        'badge access updated for new hires', 'elevator maintenance scheduled weekend',
+        'lunch order from Italian place confirmed', 'desk plants watering schedule posted',
+        'air conditioning unit serviced last week', 'office carpet cleaning Friday evening',
+        'new microwave installed in kitchen', 'visitor parking available spots three',
+        'holiday schedule posted on intranet', 'team photo session Thursday afternoon',
+        'chair ergonomics assessment signup sheet', 'standing desk adjustment instructions',
+        'kitchen fridge cleanup policy reminder', 'window blinds replaced on south side',
+        'bicycle rack installed in parking garage', 'team lunch budget increased quarterly',
+        'noise canceling headphones approved expense', 'monitor arm request form updated',
+        'desk drawer key replacement procedure', 'building security hours extended',
+    ];
+    for (let i = 0; i < noiseTopics.length; i++) {
+        entries.push(mem(`noise-${i}`, noiseTopics[i], { created: dateOffset(i), tags: ['topic:office'] }));
+    }
+    entries.push(mem('nr-1', 'The database connection pool was exhausted because max_connections was set to 10 but the application had 25 concurrent requests', {
+        created: dateOffset(20), tags: ['topic:database', 'topic:performance'],
+    }), mem('nr-2', 'The S3 bucket policy was misconfigured allowing public read access to customer data uploads', {
+        created: dateOffset(21), tags: ['topic:security', 'topic:s3'],
+    }));
+    cases.push({ id: 'nr-q1', category: 'noise-resistance', query: 'database connection pool exhausted max connections', expectedIds: ['nr-1'], description: 'find DB issue despite 30 noise entries' }, { id: 'nr-q2', category: 'noise-resistance', query: 'S3 bucket public access security misconfiguration', expectedIds: ['nr-2'], description: 'find S3 issue despite noise' }, { id: 'nr-q3', category: 'noise-resistance', query: 'PostgreSQL migration constraint', expectedIds: ['dr-1'], description: 'find earlier DB entry despite noise' }, { id: 'nr-q4', category: 'noise-resistance', query: 'JWT token security expiration', expectedIds: ['dr-5'], description: 'find security entry despite noise' });
+    // =========================================================================
+    // 6. MULTI-HOP — entity chaining across sessions
+    // =========================================================================
+    entries.push(mem('mh-1', 'speaker:Alice works on the payment gateway integration with Stripe. She found a webhook signature validation bug.', {
+        created: dateOffset(25), tags: ['speaker:Alice', 'topic:payments'],
+    }), mem('mh-2', 'speaker:Bob reviewed the Stripe webhook code and confirmed the signature validation uses the wrong secret key from the test environment.', {
+        created: dateOffset(26), tags: ['speaker:Bob', 'topic:payments'],
+    }), mem('mh-3', 'speaker:Alice fixed the Stripe webhook by switching to the production secret key. Payment confirmations now arrive within 2 seconds.', {
+        created: dateOffset(27), tags: ['speaker:Alice', 'topic:payments'],
+    }), mem('mh-4', 'speaker:Carol reported that the billing dashboard shows incorrect revenue numbers because it reads from the payments_raw table instead of payments_reconciled.', {
+        created: dateOffset(28), tags: ['speaker:Carol', 'topic:billing'],
+    }));
+    cases.push({ id: 'mh-q1', category: 'multi-hop', query: 'Who fixed the Stripe webhook bug and what was the root cause?', expectedIds: ['mh-1', 'mh-2', 'mh-3'], description: 'chain Alice -> Stripe -> Bob -> fix' }, { id: 'mh-q2', category: 'multi-hop', query: 'What are all the payment-related issues the team discussed?', expectedIds: ['mh-1', 'mh-2', 'mh-3', 'mh-4'], description: 'find all payment topics across speakers' });
+    return { entries, cases };
+}
+// ---------------------------------------------------------------------------
+// Runner — evaluates each case against the synthetic corpus
+// ---------------------------------------------------------------------------
+export async function runFeatureEval(version) {
+    const start = Date.now();
+    const { entries, cases } = buildSyntheticCorpus();
+    const caseResults = [];
+    for (const c of cases) {
+        let results;
+        if (c.category === 'multi-hop') {
+            results = multihopSearch(c.query, entries, { budget: 50000 });
+        }
+        else {
+            results = search(c.query, entries, { budget: 50000 });
+        }
+        const returnedIds = results.map(r => r.entry.id);
+        caseResults.push({
+            case: c,
+            returnedIds,
+            mrrVal: mrr(returnedIds, c.expectedIds),
+            r5: recallAtK(returnedIds, c.expectedIds, 5),
+            ndcg5: ndcgAtK(returnedIds, c.expectedIds, 5),
+        });
+    }
+    const categories = [...new Set(cases.map(c => c.category))];
+    const features = categories.map(cat => {
+        const catCases = caseResults.filter(r => r.case.category === cat);
+        const n = catCases.length;
+        const avgMrr = catCases.reduce((s, r) => s + r.mrrVal, 0) / n;
+        const avgR5 = catCases.reduce((s, r) => s + r.r5, 0) / n;
+        const avgNdcg5 = catCases.reduce((s, r) => s + r.ndcg5, 0) / n;
+        return {
+            category: cat,
+            cases: n,
+            mrr: avgMrr,
+            recallAt5: avgR5,
+            ndcgAt5: avgNdcg5,
+            passed: true,
+        };
+    });
+    const totalCases = caseResults.length;
+    const overallMrr = caseResults.reduce((s, r) => s + r.mrrVal, 0) / totalCases;
+    const overallR5 = caseResults.reduce((s, r) => s + r.r5, 0) / totalCases;
+    const overallNdcg5 = caseResults.reduce((s, r) => s + r.ndcg5, 0) / totalCases;
+    return {
+        version,
+        timestamp: new Date().toISOString(),
+        features,
+        overall: { mrr: overallMrr, recallAt5: overallR5, ndcgAt5: overallNdcg5 },
+        totalCases,
+        durationMs: Date.now() - start,
+    };
+}
+// ---------------------------------------------------------------------------
+// Regression detection
+// ---------------------------------------------------------------------------
+const REGRESSION_THRESHOLD = 0.05;
+export function detectRegressions(baseline, current) {
+    const regressions = [];
+    const improvements = [];
+    for (const feat of current.features) {
+        const base = baseline.features[feat.category];
+        if (!base)
+            continue;
+        for (const metric of ['mrr', 'recallAt5', 'ndcgAt5']) {
+            const baseVal = base[metric];
+            const curVal = feat[metric];
+            const delta = curVal - baseVal;
+            if (delta < -REGRESSION_THRESHOLD) {
+                regressions.push({ category: feat.category, metric, baseline: baseVal, current: curVal, delta });
+            }
+            else if (delta > REGRESSION_THRESHOLD) {
+                improvements.push({ category: feat.category, metric, baseline: baseVal, current: curVal, delta });
+            }
+        }
+    }
+    return {
+        regressions,
+        improvements,
+        verdict: regressions.length > 0 ? 'REGRESSION' : 'PASS',
+    };
+}
+export function resultToBaseline(result) {
+    const features = {};
+    for (const f of result.features) {
+        features[f.category] = { mrr: f.mrr, recallAt5: f.recallAt5, ndcgAt5: f.ndcgAt5 };
+    }
+    return {
+        version: result.version,
+        timestamp: result.timestamp,
+        features,
+        overall: result.overall,
+    };
+}
+// ---------------------------------------------------------------------------
+// Formatters
+// ---------------------------------------------------------------------------
+function pct(n) {
+    return (n * 100).toFixed(1) + '%';
+}
+function pad(s, w) {
+    return s.padEnd(w);
+}
+function deltaStr(d) {
+    const sign = d >= 0 ? '+' : '';
+    return sign + pct(d);
+}
+export function formatResult(result, baseline) {
+    const lines = [];
+    lines.push(`Hippo Eval v${result.version} — ${result.totalCases} queries, ${result.durationMs}ms`);
+    lines.push('');
+    lines.push(`${pad('Feature', 24)} | ${pad('MRR', 8)} | ${pad('R@5', 8)} | ${pad('NDCG@5', 8)} | ${pad('vs baseline', 12)} | verdict`);
+    lines.push(`${'─'.repeat(24)}-|-${'─'.repeat(8)}-|-${'─'.repeat(8)}-|-${'─'.repeat(8)}-|-${'─'.repeat(12)}-|${'─'.repeat(8)}`);
+    let report;
+    if (baseline) {
+        report = detectRegressions(baseline, result);
+    }
+    for (const feat of result.features) {
+        const base = baseline?.features[feat.category];
+        let vsBaseline = 'NEW';
+        let verdict = 'baseline';
+        if (base) {
+            const delta = feat.ndcgAt5 - base.ndcgAt5;
+            vsBaseline = deltaStr(delta);
+            verdict = delta < -REGRESSION_THRESHOLD ? 'REGRESS' : 'PASS';
+        }
+        lines.push(`${pad(feat.category, 24)} | ${pad(pct(feat.mrr), 8)} | ${pad(pct(feat.recallAt5), 8)} | ${pad(pct(feat.ndcgAt5), 8)} | ${pad(vsBaseline, 12)} | ${verdict}`);
+    }
+    lines.push('');
+    lines.push(`Overall: MRR ${pct(result.overall.mrr)} | R@5 ${pct(result.overall.recallAt5)} | NDCG@5 ${pct(result.overall.ndcgAt5)}`);
+    if (report) {
+        if (report.verdict === 'REGRESSION') {
+            lines.push('');
+            lines.push(`REGRESSIONS DETECTED (>${pct(REGRESSION_THRESHOLD)} drop):`);
+            for (const r of report.regressions) {
+                lines.push(`  ${r.category}.${r.metric}: ${pct(r.baseline)} -> ${pct(r.current)} (${deltaStr(r.delta)})`);
+            }
+        }
+        if (report.improvements.length > 0) {
+            lines.push('');
+            lines.push('Improvements:');
+            for (const imp of report.improvements) {
+                lines.push(`  ${imp.category}.${imp.metric}: ${pct(imp.baseline)} -> ${pct(imp.current)} (${deltaStr(imp.delta)})`);
+            }
+        }
+        lines.push('');
+        lines.push(`Verdict: ${report.verdict}${report.regressions.length > 0 ? ` (${report.regressions.length} regressions)` : ''}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=eval-suite.js.map