hippo-memory 1.44.0 → 1.46.0

package/dist/eval-stats.js

@@ -0,0 +1,187 @@
+/**
+ * Statistics and cost accounting for the token-efficiency evals (ROADMAP
+ * Part IX, TE3-TE5).
+ *
+ * - 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.
+ */
+/** Sum several usages bucket by bucket. */
+export function addUsage(...usages) {
+    const total = { inputTokens: 0, cacheWriteTokens: 0, cacheReadTokens: 0, outputTokens: 0 };
+    for (const u of usages) {
+        total.inputTokens += u.inputTokens;
+        total.cacheWriteTokens += u.cacheWriteTokens;
+        total.cacheReadTokens += u.cacheReadTokens;
+        total.outputTokens += u.outputTokens;
+    }
+    return total;
+}
+/** Dollar cost of `usage` at `prices`. */
+export function priceUsage(usage, prices) {
+    return (usage.inputTokens * prices.inputPerMTok
+        + usage.cacheWriteTokens * prices.cacheWritePerMTok
+        + usage.cacheReadTokens * prices.cacheReadPerMTok
+        + usage.outputTokens * prices.outputPerMTok) / 1_000_000;
+}
+/** Default cache price ratios (write 1.25x, read 0.1x of base input). */
+export const DEFAULT_CACHE_RATIOS = { write: 1.25, read: 0.1 };
+/** Input cost of `usage` in uncached-equivalent tokens (output excluded). */
+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.
+ */
+export function seededRandom(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+function percentileInterval(samples, alpha) {
+    const sorted = [...samples].sort((x, y) => x - y);
+    const lowIdx = Math.max(0, Math.floor((alpha / 2) * sorted.length));
+    const highIdx = Math.min(sorted.length - 1, Math.ceil((1 - alpha / 2) * sorted.length) - 1);
+    return { low: sorted[lowIdx], high: sorted[highIdx] };
+}
+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.
+ */
+export function pairedBootstrap(diffs, opts = {}) {
+    const iterations = opts.iterations ?? 5000;
+    const alpha = opts.alpha ?? 0.05;
+    if (diffs.length === 0)
+        return { estimate: 0, low: 0, high: 0, iterations: 0 };
+    const rand = seededRandom(opts.seed ?? 1);
+    const n = diffs.length;
+    const samples = [];
+    for (let b = 0; b < iterations; b++) {
+        let s = 0;
+        for (let i = 0; i < n; i++)
+            s += diffs[Math.floor(rand() * n)];
+        samples.push(s / n);
+    }
+    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.
+ */
+export function clusteredPairedBootstrap(diffsByCluster, opts = {}) {
+    const iterations = opts.iterations ?? 5000;
+    const alpha = opts.alpha ?? 0.05;
+    const clusters = [...diffsByCluster.values()].filter((c) => c.length > 0);
+    const all = clusters.flat();
+    if (all.length === 0)
+        return { estimate: 0, low: 0, high: 0, iterations: 0 };
+    const rand = seededRandom(opts.seed ?? 1);
+    const k = clusters.length;
+    const samples = [];
+    for (let b = 0; b < iterations; b++) {
+        let sum = 0;
+        let count = 0;
+        for (let i = 0; i < k; i++) {
+            const c = clusters[Math.floor(rand() * k)];
+            for (const d of c)
+                sum += d;
+            count += c.length;
+        }
+        samples.push(count === 0 ? 0 : sum / count);
+    }
+    return { estimate: mean(all), ...percentileInterval(samples, alpha), iterations };
+}
+function costPerResolved(outcomes) {
+    const resolved = outcomes.filter((o) => o.resolved).length;
+    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.
+ */
+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');
+    }
+    const iterations = opts.iterations ?? 5000;
+    const alpha = opts.alpha ?? 0.05;
+    const c = costPerResolved(control);
+    const t = costPerResolved(treatment);
+    const rand = seededRandom(opts.seed ?? 1);
+    const n = control.length;
+    const deltas = [];
+    const relatives = [];
+    for (let b = 0; b < iterations && n > 0; b++) {
+        const cs = [];
+        const ts = [];
+        for (let i = 0; i < n; i++) {
+            const j = Math.floor(rand() * n);
+            cs.push(control[j]);
+            ts.push(treatment[j]);
+        }
+        const cc = costPerResolved(cs);
+        const tt = costPerResolved(ts);
+        if (!Number.isFinite(cc) || !Number.isFinite(tt))
+            continue;
+        deltas.push(tt - cc);
+        relatives.push((tt - cc) / cc);
+    }
+    const finite = Number.isFinite(c) && Number.isFinite(t);
+    const empty = { low: Number.NaN, high: Number.NaN };
+    return {
+        control: c,
+        treatment: t,
+        delta: {
+            estimate: finite ? t - c : Number.NaN,
+            ...(deltas.length > 0 ? percentileInterval(deltas, alpha) : empty),
+            iterations: deltas.length,
+        },
+        relative: {
+            estimate: finite ? (t - c) / c : Number.NaN,
+            ...(relatives.length > 0 ? percentileInterval(relatives, alpha) : empty),
+            iterations: relatives.length,
+        },
+    };
+}
+/**
+ * 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.
+ */
+export function passHatK(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).every(Boolean)).length / eligible.length;
+}
+//# sourceMappingURL=eval-stats.js.map

package/dist/extract.d.ts

@@ -8,6 +8,8 @@ export interface ExtractOptions {
     apiKey: string;
     model?: string;
     fetcher?: typeof fetch;
+    /** Told why a call produced nothing, so callers can surface it instead of guessing. */
+    onError?: (msg: string) => void;
 }
 export declare function extractFacts(text: string, opts: ExtractOptions): Promise<ExtractedFact[]>;
 export declare function storeExtractedFacts(hippoRoot: string, source: MemoryEntry, facts: ExtractedFact[]): MemoryEntry[];

package/dist/extract.js

@@ -1,6 +1,7 @@
 import { Layer, createMemory } from './memory.js';
 import { writeEntry } from './store.js';
 import { RejectedValueError } from './rejection.js';
+import { redactSecrets } from './secret-detect.js';
 function isJsonString(value) {
     return typeof value === 'string';
 }
@@ -31,15 +32,18 @@ export async function extractFacts(text, opts) {
             body: JSON.stringify({
                 model,
                 max_tokens: 1200,
-                messages: [{ role: 'user', content: EXTRACTION_PROMPT + text }],
+                messages: [{ role: 'user', content: EXTRACTION_PROMPT + redactSecrets(text) }],
             }),
         });
     }
-    catch {
+    catch (err) {
+        opts.onError?.(`request failed: ${err instanceof Error ? err.message : String(err)}`);
         return [];
     }
-    if (!res.ok)
+    if (!res.ok) {
+        opts.onError?.(`HTTP ${res.status}`);
         return [];
+    }
     try {
         const data = await res.json();
         const raw = data.content?.[0]?.text?.trim() ?? '';
@@ -69,7 +73,8 @@ export async function extractFacts(text, opts) {
         }
         return facts;
     }
-    catch {
+    catch (err) {
+        opts.onError?.(`unparseable response: ${err instanceof Error ? err.message : String(err)}`);
         return [];
     }
 }

package/dist/half-life-migration.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Moving a store's memories to a new default half-life.
+ *
+ * Each memory stores its own `half_life_days`, set at write from the
+ * default base and a few write-time multipliers (`deriveHalfLife`). Changing
+ * the default therefore reaches only new memories; without this migration a
+ * store would mix old-base and new-base memories, a state the decay
+ * evaluation never tested (docs/evals/2026-09-24-decay-default-prereg.md,
+ * Migration). The rule, declared there before any run:
+ *
+ * - only a memory still on the old base is rescaled: its half-life is
+ *   `deriveHalfLife(from, entry)` plus its recall bonus. A memory hippo shortened since
+ *   (invalidated, superseded, a merge source, marked bad) or one with its own
+ *   fixed half-life (decisions, incidents, customer notes) keeps its value;
+ * - every rescale is written to the audit log with the ids, so it can be
+ *   undone, and the store records the base it is on (`meta`), so the
+ *   migration runs once.
+ *
+ * `hippo sleep` runs it before its decay pass, from the base the store is on
+ * (7 days when never recorded) to the configured `defaultHalfLifeDays`.
+ */
+import { type MemoryEntry } from './memory.js';
+import { HALF_LIFE_BASE_META_KEY } from './store.js';
+/** The base every store used before the base was recorded. */
+export declare const LEGACY_HALF_LIFE_BASE = 7;
+export { HALF_LIFE_BASE_META_KEY };
+/** What {@link migrateDefaultHalfLife} did, or would do under `dryRun`. */
+export interface HalfLifeMigrationResult {
+    from: number;
+    to: number;
+    /** Memories moved to the new base. */
+    rescaled: number;
+    /** Memories left alone because they are not on the old base. */
+    kept: number;
+    dryRun: boolean;
+    /** New half-life per moved id, so a dry run can preview decay at the new base. */
+    halfLives: ReadonlyMap<string, number>;
+}
+type HalfLifeFields = Pick<MemoryEntry, 'half_life_days' | 'tags' | 'schema_fit' | 'retrieval_count' | 'superseded_by'>;
+/** Recall bonus over what `base` gave `entry`, or null when off that base; pre-1.46 recalls each added 2 days. */
+export declare function halfLifeRecallBonus(entry: HalfLifeFields, base: number): number | null;
+/** The entries to rescale from `from` to `to`, as copies that keep their recall bonus. Pure. */
+export declare function planHalfLifeMigration(entries: readonly MemoryEntry[], from: number, to: number): MemoryEntry[];
+/** The base this store's memories are on. */
+export declare function storeHalfLifeBase(hippoRoot: string): number;
+/**
+ * Move the store's memories from the base they are on to `to`. A no-op when
+ * they are already on it. Under `dryRun` nothing is written, the recorded
+ * base included.
+ */
+export declare function migrateDefaultHalfLife(hippoRoot: string, to: number, opts?: {
+    dryRun?: boolean;
+    actor?: string;
+}): HalfLifeMigrationResult;
+//# sourceMappingURL=half-life-migration.d.ts.map

package/dist/half-life-migration.js

@@ -0,0 +1,111 @@
+/**
+ * Moving a store's memories to a new default half-life.
+ *
+ * Each memory stores its own `half_life_days`, set at write from the
+ * default base and a few write-time multipliers (`deriveHalfLife`). Changing
+ * the default therefore reaches only new memories; without this migration a
+ * store would mix old-base and new-base memories, a state the decay
+ * evaluation never tested (docs/evals/2026-09-24-decay-default-prereg.md,
+ * Migration). The rule, declared there before any run:
+ *
+ * - only a memory still on the old base is rescaled: its half-life is
+ *   `deriveHalfLife(from, entry)` plus its recall bonus. A memory hippo shortened since
+ *   (invalidated, superseded, a merge source, marked bad) or one with its own
+ *   fixed half-life (decisions, incidents, customer notes) keeps its value;
+ * - every rescale is written to the audit log with the ids, so it can be
+ *   undone, and the store records the base it is on (`meta`), so the
+ *   migration runs once.
+ *
+ * `hippo sleep` runs it before its decay pass, from the base the store is on
+ * (7 days when never recorded) to the configured `defaultHalfLifeDays`.
+ */
+import { deriveHalfLife } from './memory.js';
+import { initStore, selectAllEntries, HALF_LIFE_BASE_META_KEY } from './store.js';
+import { openHippoDb, closeHippoDb, getMeta, setMeta } from './db.js';
+import { appendAuditEvent } from './audit.js';
+/** The base every store used before the base was recorded. */
+export const LEGACY_HALF_LIFE_BASE = 7;
+export { HALF_LIFE_BASE_META_KEY };
+/** Recall bonus over what `base` gave `entry`, or null when off that base; pre-1.46 recalls each added 2 days. */
+export function halfLifeRecallBonus(entry, base) {
+    if (entry.superseded_by || entry.tags.includes('invalidated') || entry.tags.includes('superseded'))
+        return null;
+    const bonus = entry.half_life_days - deriveHalfLife(base, entry);
+    const k = Math.round(bonus / 2);
+    return Math.abs(bonus - 2 * k) < 1e-9 && k >= 0 && k <= entry.retrieval_count ? bonus : null;
+}
+/** The entries to rescale from `from` to `to`, as copies that keep their recall bonus. Pure. */
+export function planHalfLifeMigration(entries, from, to) {
+    if (from === to)
+        return [];
+    return entries.flatMap((e) => {
+        const bonus = halfLifeRecallBonus(e, from);
+        return bonus === null ? [] : [{ ...e, half_life_days: deriveHalfLife(to, e) + bonus }];
+    });
+}
+/** The base this store's memories are on. */
+export function storeHalfLifeBase(hippoRoot) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        return readBase(db);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+function readBase(db) {
+    const raw = Number(getMeta(db, HALF_LIFE_BASE_META_KEY, String(LEGACY_HALF_LIFE_BASE)));
+    return Number.isFinite(raw) && raw > 0 ? raw : LEGACY_HALF_LIFE_BASE;
+}
+/**
+ * Move the store's memories from the base they are on to `to`. A no-op when
+ * they are already on it. Under `dryRun` nothing is written, the recorded
+ * base included.
+ */
+export function migrateDefaultHalfLife(hippoRoot, to, opts = {}) {
+    const dryRun = opts.dryRun ?? false;
+    const noop = (from) => ({ from, to, rescaled: 0, kept: 0, dryRun, halfLives: new Map() });
+    initStore(hippoRoot);
+    const db = openHippoDb(hippoRoot);
+    try {
+        // Plan, write, audit and record the base under one write lock, so a concurrent write or sleep cannot interleave.
+        if (!dryRun)
+            db.exec('BEGIN IMMEDIATE');
+        try {
+            const from = readBase(db);
+            if (!(Number.isFinite(to) && to > 0) || from === to) {
+                if (!dryRun)
+                    db.exec('COMMIT');
+                return noop(from);
+            }
+            const all = selectAllEntries(db);
+            const plan = planHalfLifeMigration(all, from, to);
+            const halfLives = new Map(plan.map((e) => [e.id, e.half_life_days]));
+            const result = { from, to, rescaled: plan.length, kept: all.length - plan.length, dryRun, halfLives };
+            if (dryRun)
+                return result;
+            const old = new Map(all.map((e) => [e.id, e.half_life_days]));
+            const update = db.prepare('UPDATE memories SET half_life_days = ? WHERE id = ?');
+            const byTenant = new Map();
+            for (const e of plan) {
+                update.run(e.half_life_days, e.id);
+                byTenant.set(e.tenantId, { ...byTenant.get(e.tenantId), [e.id]: old.get(e.id) });
+            }
+            for (const [tenantId, oldHalfLives] of byTenant) {
+                appendAuditEvent(db, { tenantId, actor: opts.actor ?? 'system', op: 'half_life_migrate', metadata: { from, to, ids: Object.keys(oldHalfLives), oldHalfLives } });
+            }
+            setMeta(db, HALF_LIFE_BASE_META_KEY, String(to));
+            db.exec('COMMIT');
+            return result;
+        }
+        catch (err) {
+            if (!dryRun)
+                db.exec('ROLLBACK');
+            throw err;
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=half-life-migration.js.map

package/dist/hooks.d.ts

@@ -85,6 +85,10 @@ export interface InstallResult {
     installedUserPromptSubmit: boolean;
     installedPreCompact: boolean;
     installedCompactResume: boolean;
+    /** PostCompact -> `hippo post-compact` (tells the user what compaction saved). */
+    installedPostCompact: boolean;
+    /** PostToolUseFailure -> `hippo capture-error` (failed tool calls become error memories). */
+    installedCaptureError: boolean;
     migratedPinnedInjectRecent: boolean;
     migratedFromStop: boolean;
     migratedLegacySessionEnd: boolean;

package/dist/hooks.js

@@ -52,6 +52,8 @@ const HIPPO_PINNED_INJECT_COMMAND = 'hippo context --pinned-only --include-recen
 const HIPPO_CODEX_WRAPPER_MARKER = 'hippo codex wrapper';
 const HIPPO_PRE_COMPACT_MARKER = 'hippo pre-compact';
 const HIPPO_COMPACT_RESUME_MARKER = 'hippo compact-resume';
+const HIPPO_CAPTURE_ERROR_MARKER = 'hippo capture-error';
+const HIPPO_POST_COMPACT_MARKER = 'hippo post-compact';
 const HIPPO_OPENCODE_PLUGIN_MARKER = 'HIPPO_OPENCODE_PLUGIN_V1';
 /**
  * The opencode plugin file we install at ~/.config/opencode/plugins/hippo.ts.
@@ -571,6 +573,8 @@ export function installJsonHooks(target) {
                 installedUserPromptSubmit: false,
                 installedPreCompact: false,
                 installedCompactResume: false,
+                installedPostCompact: false,
+                installedCaptureError: false,
                 migratedPinnedInjectRecent: false,
                 migratedFromStop: false,
                 migratedLegacySessionEnd: false,
@@ -703,11 +707,50 @@ export function installJsonHooks(target) {
         });
         installedCompactResume = true;
     }
+    // PostCompact: tells the user what pre-compact saved. PreCompact itself
+    // must stay silent, because Claude Code hands PreCompact stdout to the
+    // summarising model as instructions; PostCompact stdout is only shown.
+    let installedPostCompact = false;
+    if (!hookArrayContains(hooks.PostCompact, HIPPO_POST_COMPACT_MARKER)) {
+        if (!Array.isArray(hooks.PostCompact))
+            hooks.PostCompact = [];
+        hooks.PostCompact.push({
+            hooks: [
+                {
+                    type: 'command',
+                    command: `hippo post-compact --log-file "${defaultPreCompactLogPath()}"`,
+                    timeout: 10,
+                },
+            ],
+        });
+        installedPostCompact = true;
+    }
+    // PostToolUseFailure: a failed tool call becomes an error memory, after
+    // `hippo capture-error` drops routine failures (interrupts, declined
+    // permissions, empty searches) and repeats. Same hook the plugin ships.
+    let installedCaptureError = false;
+    if (!hookArrayContains(hooks.PostToolUseFailure, HIPPO_CAPTURE_ERROR_MARKER)) {
+        if (!Array.isArray(hooks.PostToolUseFailure))
+            hooks.PostToolUseFailure = [];
+        hooks.PostToolUseFailure.push({
+            matcher: '.*',
+            hooks: [
+                {
+                    type: 'command',
+                    command: 'hippo capture-error',
+                    timeout: 10,
+                },
+            ],
+        });
+        installedCaptureError = true;
+    }
     if (installedSessionEnd ||
         installedSessionStart ||
         installedUserPromptSubmit ||
         installedPreCompact ||
         installedCompactResume ||
+        installedPostCompact ||
+        installedCaptureError ||
         migratedPinnedInjectRecent ||
         migratedFromStop ||
         migratedLegacySessionEnd ||
@@ -722,6 +765,8 @@ export function installJsonHooks(target) {
         installedUserPromptSubmit,
         installedPreCompact,
         installedCompactResume,
+        installedPostCompact,
+        installedCaptureError,
         migratedPinnedInjectRecent,
         migratedFromStop,
         migratedLegacySessionEnd,
@@ -753,6 +798,8 @@ export function uninstallJsonHooks(target) {
         SessionStart: [HIPPO_LAST_SLEEP_MARKER, HIPPO_COMPACT_RESUME_MARKER],
         UserPromptSubmit: [HIPPO_PINNED_INJECT_MARKER],
         PreCompact: [HIPPO_PRE_COMPACT_MARKER],
+        PostCompact: [HIPPO_POST_COMPACT_MARKER],
+        PostToolUseFailure: [HIPPO_CAPTURE_ERROR_MARKER],
         Stop: [HIPPO_SLEEP_MARKER],
     };
     for (const [key, markers] of Object.entries(markersByKey)) {

package/dist/mcp/server.d.ts

@@ -42,6 +42,12 @@ export interface McpContext {
     hippoRoot: string;
     tenantId: string;
     actor: string;
+    /**
+     * The caller's role from the HTTP transport's auth. Absent for stdio, which
+     * is the local operator and runs as admin. Tools must use this rather than
+     * assuming admin, or a member key over HTTP-MCP would act as admin.
+     */
+    role?: 'admin' | 'member';
     /**
      * Per-client key for state isolation under HTTP-MCP. For stdio: 'stdio-${pid}'
      * (one process = one client). For HTTP-SSE / HTTP MCP: hash(bearer + remoteAddr)