hippo-memory 1.45.0 → 1.46.0

package/dist/dormant.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Dormant memories: what sleep does with a faded memory instead of deleting
+ * it (config `dormant.enabled`, on by default; `retentionDays` bounds how
+ * long one is kept).
+ *
+ * A dormant memory keeps its full content in `dormant_memories` (schema v44)
+ * but is no longer a `memories` row, so recall, context, every sleep pass and
+ * every other reader of `memories` stop seeing it exactly as if it had been
+ * deleted. `hippo dormant` lists and searches them, `hippo dormant restore`
+ * brings one back, `hippo dormant forget` deletes one for good.
+ *
+ * Not to be confused with the raw archive (`raw_archive`, `archiveRawMemory`,
+ * `hippo forget --archive`): that path removes a raw receipt's content and
+ * keeps only its metadata. A dormant memory keeps its content.
+ *
+ * DB-only helpers: the caller owns the handle and any transaction. The
+ * tenant-scoped entry points are api.listDormant / restoreDormant /
+ * forgetDormant.
+ */
+import type { DatabaseSyncLike } from './db.js';
+import type { MemoryEntry } from './memory.js';
+/** Why sleep made a memory dormant. Only the decay pass does today. */
+export type DormantReason = 'decay';
+/** One memory that sleep is moving out of active memory into the dormant store. */
+export interface DormantMove {
+    /** The memory as it stood when it faded; restored verbatim apart from its recall clock. */
+    entry: MemoryEntry;
+    /** Live strength at the moment it went dormant (below the decay threshold). */
+    strength: number;
+    reason: DormantReason;
+    /** ISO time of the sleep that made it dormant. */
+    dormantAt: string;
+}
+/** A dormant memory as listed to a user. */
+export interface DormantMemory {
+    id: string;
+    tenantId: string;
+    content: string;
+    tags: string[];
+    /** Live strength when it went dormant. */
+    strength: number;
+    /** Why it went dormant (`decay`). */
+    reason: string;
+    /** ISO time it went dormant. */
+    dormantAt: string;
+}
+/** Options for {@link listDormantRows}. */
+export interface ListDormantOpts {
+    /** Whitespace-separated terms; a row must contain every term (case-insensitive substring). */
+    query?: string;
+    /** Maximum rows returned, newest first. Default 20. */
+    limit?: number;
+}
+/**
+ * Insert (or refresh) the dormant snapshot for `move.entry`. Does not touch
+ * the `memories` row: the caller deletes it in the same transaction, so the
+ * memory is never in both places or in neither.
+ */
+export declare function insertDormantRow(db: DatabaseSyncLike, move: DormantMove): void;
+/** A tenant's dormant memories, newest first, optionally filtered by search terms. */
+export declare function listDormantRows(db: DatabaseSyncLike, tenantId: string, opts?: ListDormantOpts): DormantMemory[];
+/** A dormant memory's stored snapshot plus when and why it went dormant. */
+export interface DormantSnapshot {
+    entry: MemoryEntry;
+    reason: string;
+    strength: number;
+    dormantAt: string;
+}
+/**
+ * The stored snapshot for a tenant's dormant memory, or null when the tenant
+ * has no dormant memory with that id (another tenant's id reads as absent).
+ */
+export declare function readDormantSnapshot(db: DatabaseSyncLike, tenantId: string, id: string): DormantSnapshot | null;
+/** Whether a tenant has a dormant memory with this id (snapshot readable or not). */
+export declare function hasDormantRow(db: DatabaseSyncLike, tenantId: string, id: string): boolean;
+/** Delete a tenant's dormant memory. Returns false when there was none. */
+export declare function deleteDormantRow(db: DatabaseSyncLike, tenantId: string, id: string): boolean;
+/**
+ * Delete every dormant memory in the tenant whose content has this rejection
+ * digest, so a rejected value cannot linger in dormant storage. Returns the
+ * ids removed. Same O(N) scan as the live-row sweep in reject-flow.ts.
+ */
+export declare function purgeDormantByDigest(db: DatabaseSyncLike, tenantId: string, digest: string): string[];
+/** How many dormant memories went dormant before `cutoffIso` (a dry-run count). */
+export declare function countExpiredDormant(db: DatabaseSyncLike, cutoffIso: string): number;
+/**
+ * Delete every dormant memory (all tenants) that went dormant before
+ * `cutoffIso`: the `dormant.retentionDays` window. Returns how many went.
+ */
+export declare function purgeExpiredDormant(db: DatabaseSyncLike, cutoffIso: string): number;
+//# sourceMappingURL=dormant.d.ts.map

package/dist/dormant.js

@@ -0,0 +1,121 @@
+import { rejectionDigest } from './rejection.js';
+const DEFAULT_LIST_LIMIT = 20;
+/**
+ * Insert (or refresh) the dormant snapshot for `move.entry`. Does not touch
+ * the `memories` row: the caller deletes it in the same transaction, so the
+ * memory is never in both places or in neither.
+ */
+export function insertDormantRow(db, move) {
+    db.prepare(`
+    INSERT INTO dormant_memories (tenant_id, id, content, entry_json, reason, strength, dormant_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(tenant_id, id) DO UPDATE SET
+      content = excluded.content,
+      entry_json = excluded.entry_json,
+      reason = excluded.reason,
+      strength = excluded.strength,
+      dormant_at = excluded.dormant_at
+  `).run(move.entry.tenantId, move.entry.id, move.entry.content, JSON.stringify(move.entry), move.reason, move.strength, move.dormantAt);
+}
+/** Escape LIKE metacharacters so a search term matches literally (ESCAPE '\'). */
+function escapeLike(term) {
+    return term.replace(/[\\%_]/g, (ch) => `\\${ch}`);
+}
+/**
+ * Parse a stored snapshot back into a MemoryEntry, or null when the row no
+ * longer matches the snapshot it carries (edited by hand, or truncated).
+ */
+function parseSnapshot(row) {
+    try {
+        // SAFETY: entry_json is only written by insertDormantRow from a MemoryEntry;
+        // the id / tenant / content checks below reject a row edited out of shape.
+        const entry = JSON.parse(row.entry_json);
+        if (entry.id !== row.id || entry.tenantId !== row.tenant_id || entry.content !== row.content) {
+            return null;
+        }
+        return entry;
+    }
+    catch {
+        return null;
+    }
+}
+function rowToDormantMemory(row) {
+    const entry = parseSnapshot(row);
+    return {
+        id: row.id,
+        tenantId: row.tenant_id,
+        content: row.content,
+        tags: entry && Array.isArray(entry.tags) ? entry.tags.map(String) : [],
+        strength: row.strength,
+        reason: row.reason,
+        dormantAt: row.dormant_at,
+    };
+}
+/** A tenant's dormant memories, newest first, optionally filtered by search terms. */
+export function listDormantRows(db, tenantId, opts = {}) {
+    const terms = (opts.query ?? '').trim().split(/\s+/).filter((t) => t.length > 0);
+    const limit = opts.limit !== undefined && Number.isFinite(opts.limit) && opts.limit >= 1
+        ? Math.floor(opts.limit)
+        : DEFAULT_LIST_LIMIT;
+    const termClauses = terms.map(() => ` AND content LIKE ? ESCAPE '\\'`).join('');
+    // SAFETY: rows' shape matches the seven columns named in the SELECT.
+    const rows = db.prepare(`SELECT tenant_id, id, content, entry_json, reason, strength, dormant_at
+       FROM dormant_memories
+      WHERE tenant_id = ?${termClauses}
+      ORDER BY dormant_at DESC, id ASC
+      LIMIT ?`).all(tenantId, ...terms.map((t) => `%${escapeLike(t)}%`), limit);
+    return rows.map(rowToDormantMemory);
+}
+/**
+ * The stored snapshot for a tenant's dormant memory, or null when the tenant
+ * has no dormant memory with that id (another tenant's id reads as absent).
+ */
+export function readDormantSnapshot(db, tenantId, id) {
+    // SAFETY: row's shape matches the seven columns named in the SELECT.
+    const row = db.prepare(`SELECT tenant_id, id, content, entry_json, reason, strength, dormant_at
+       FROM dormant_memories WHERE tenant_id = ? AND id = ?`).get(tenantId, id);
+    const entry = row ? parseSnapshot(row) : null;
+    return row && entry ? { entry, reason: row.reason, strength: row.strength, dormantAt: row.dormant_at } : null;
+}
+/** Whether a tenant has a dormant memory with this id (snapshot readable or not). */
+export function hasDormantRow(db, tenantId, id) {
+    return db.prepare(`SELECT 1 FROM dormant_memories WHERE tenant_id = ? AND id = ?`).get(tenantId, id) !== undefined;
+}
+/** Delete a tenant's dormant memory. Returns false when there was none. */
+export function deleteDormantRow(db, tenantId, id) {
+    const result = db.prepare(`DELETE FROM dormant_memories WHERE tenant_id = ? AND id = ?`).run(tenantId, id);
+    return Number(result.changes ?? 0) > 0;
+}
+/**
+ * Delete every dormant memory in the tenant whose content has this rejection
+ * digest, so a rejected value cannot linger in dormant storage. Returns the
+ * ids removed. Same O(N) scan as the live-row sweep in reject-flow.ts.
+ */
+export function purgeDormantByDigest(db, tenantId, digest) {
+    // SAFETY: rows' shape matches the two columns named in the SELECT.
+    const rows = db.prepare(`SELECT id, content FROM dormant_memories WHERE tenant_id = ?`)
+        .all(tenantId);
+    const removed = [];
+    for (const row of rows) {
+        if (rejectionDigest(row.content) !== digest)
+            continue;
+        deleteDormantRow(db, tenantId, row.id);
+        removed.push(row.id);
+    }
+    return removed;
+}
+/** How many dormant memories went dormant before `cutoffIso` (a dry-run count). */
+export function countExpiredDormant(db, cutoffIso) {
+    // SAFETY: row's shape matches the single aliased COUNT column in the SELECT.
+    const row = db.prepare(`SELECT COUNT(*) AS n FROM dormant_memories WHERE dormant_at < ?`).get(cutoffIso);
+    return Number(row.n);
+}
+/**
+ * Delete every dormant memory (all tenants) that went dormant before
+ * `cutoffIso`: the `dormant.retentionDays` window. Returns how many went.
+ */
+export function purgeExpiredDormant(db, cutoffIso) {
+    const result = db.prepare(`DELETE FROM dormant_memories WHERE dormant_at < ?`).run(cutoffIso);
+    return Number(result.changes ?? 0);
+}
+//# sourceMappingURL=dormant.js.map

package/dist/eval-stats.d.ts

@@ -0,0 +1,123 @@
+/**
+ * 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.
+ */
+/** 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). */
+    inputTokens: number;
+    /** Input tokens written to a prompt cache. */
+    cacheWriteTokens: number;
+    /** Input tokens read from a prompt cache. */
+    cacheReadTokens: number;
+    /** 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.
+ */
+export interface Prices {
+    inputPerMTok: number;
+    cacheWritePerMTok: number;
+    cacheReadPerMTok: number;
+    outputPerMTok: number;
+}
+/** Sum several usages bucket by bucket. */
+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.
+ */
+export interface CacheRatios {
+    write: number;
+    read: number;
+}
+/** Default cache price ratios (write 1.25x, read 0.1x of base input). */
+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.
+ */
+export declare function seededRandom(seed: number): () => number;
+/** A point estimate with a percentile bootstrap confidence interval. */
+export interface Estimate {
+    estimate: number;
+    low: number;
+    high: number;
+    /** Resamples drawn. */
+    iterations: number;
+}
+/** Options shared by the bootstrap functions. */
+export interface BootstrapOpts {
+    /** Resamples. Default 5000. */
+    iterations?: number;
+    /** Two-sided level, e.g. 0.05 for a 95% interval. Default 0.05. */
+    alpha?: number;
+    /** 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.
+ */
+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.
+ */
+export declare function clusteredPairedBootstrap(diffsByCluster: ReadonlyMap<string, number[]>, opts?: BootstrapOpts): Estimate;
+/** One task's outcome in one arm, for {@link costPerResolvedDelta}. */
+export interface ArmOutcome {
+    /** Dollars (or uncached-equivalent tokens) spent on the task. */
+    cost: number;
+    /** Whether the task was resolved. */
+    resolved: boolean;
+}
+/** Result of {@link costPerResolvedDelta}. */
+export interface CostPerResolvedDelta {
+    control: number;
+    treatment: number;
+    /** treatment minus control, with its interval. */
+    delta: Estimate;
+    /** (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.
+ */
+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).
+ */
+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.
+ */
+export declare function passHatK(runsByTask: boolean[][], k: number): number;
+//# sourceMappingURL=eval-stats.d.ts.map

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/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