hippo-memory 1.69.0 → 1.71.0

package/dist/store/diagnostics.d.ts

@@ -0,0 +1,47 @@
+import { type CompactionCounts, type TokenTally } from './doctor-reads.js';
+import type { JsonObject } from './working-memory.js';
+/** One read's value, or the message of the error that stopped it, so a broken table never hides the reads beside it. */
+export type Attempt<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/** ISO times the health reads count from. */
+export interface HealthCutoffs {
+    /** Token and failure rows at or after this count. */
+    readonly since: string;
+    /** A compaction unfinished since before this is stuck. */
+    readonly stuckBefore: string;
+    /** A started compaction older than this is past replaying. */
+    readonly transcriptFloor: string;
+}
+export interface StoreHealth {
+    readonly schemaVersion: number;
+    /** Null when the table is missing or unreadable. */
+    readonly memories: number | null;
+    readonly dormant: number | null;
+    /** Null inside a read that worked means the store has no full-text index. */
+    readonly fts: Attempt<{
+        memories: number;
+        fts: number;
+    } | null>;
+    readonly tokens: Attempt<TokenTally>;
+    readonly failures: Attempt<number>;
+    /** Undefined inside a read that worked means the store never slept. */
+    readonly lastSleep: Attempt<string | undefined>;
+    readonly compactions: Attempt<CompactionCounts>;
+}
+/** Everything `hippo doctor` reads from one store; throws when it cannot be opened or its schema version read. */
+export declare function readStoreHealth(hippoRoot: string, cutoffs: HealthCutoffs): StoreHealth;
+export interface StoreInventory {
+    readonly schemaVersion: number;
+    /** Oldest hippo binary the store allows, or null when it names none. */
+    readonly minCompatibleBinary: string | null;
+    /** Row count by table name; null for a table that cannot be counted. */
+    readonly tables: JsonObject;
+}
+/** Schema version, oldest allowed binary and row count of every table, for a support bundle; never reads a memory column. */
+export declare function readStoreInventory(hippoRoot: string): StoreInventory;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/store/diagnostics.js

@@ -0,0 +1,44 @@
+// What `hippo doctor` and `hippo support-bundle` read from a store: one read-only open each, plain data out.
+import { countTableRows, ftsRowCounts, getMeta, getSchemaVersion, openHippoDbReadOnly } from '../db/index.js';
+import { onHandle } from './open.js';
+import { listTableNames } from '../db/tables.js';
+import { errorMessage } from '../util/log.js';
+import { compactionCountsAt, tokenTallySince } from './doctor-reads.js';
+import { countFailuresSince } from './failure-log.js';
+import { lastConsolidationAt } from './index-and-stats.js';
+function attempt(read) {
+    try {
+        return { ok: true, value: read() };
+    }
+    catch (err) {
+        // The caller turns the message into its own check, so the error stops here.
+        return { ok: false, message: errorMessage(err) };
+    }
+}
+/** Everything `hippo doctor` reads from one store; throws when it cannot be opened or its schema version read. */
+export function readStoreHealth(hippoRoot, cutoffs) {
+    return onHandle(hippoRoot, (db) => {
+        return {
+            schemaVersion: getSchemaVersion(db),
+            memories: countTableRows(db, 'memories'),
+            dormant: countTableRows(db, 'dormant_memories'),
+            fts: attempt(() => ftsRowCounts(db)),
+            tokens: attempt(() => tokenTallySince(db, cutoffs.since)),
+            failures: attempt(() => countFailuresSince(db, cutoffs.since)),
+            lastSleep: attempt(() => lastConsolidationAt(db)),
+            compactions: attempt(() => compactionCountsAt(db, cutoffs.stuckBefore, cutoffs.transcriptFloor)),
+        };
+    }, openHippoDbReadOnly);
+}
+/** Schema version, oldest allowed binary and row count of every table, for a support bundle; never reads a memory column. */
+export function readStoreInventory(hippoRoot) {
+    return onHandle(hippoRoot, (db) => {
+        const schemaVersion = getSchemaVersion(db);
+        const minCompatibleBinary = getMeta(db, 'min_compatible_binary', '') || null;
+        const tables = {};
+        for (const name of listTableNames(db))
+            tables[name] = countTableRows(db, name);
+        return { schemaVersion, minCompatibleBinary, tables };
+    }, openHippoDbReadOnly);
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/store/doctor-reads.d.ts

@@ -0,0 +1,16 @@
+import type { DatabaseSyncLike } from '../db/index.js';
+export interface CompactionCounts {
+    total: number;
+    summarised: number;
+    started: number;
+}
+/** Compaction records in all, those with a summary whose memories never got saved, and those still without a summary; each cutoff is an ISO time. */
+export declare function compactionCountsAt(db: DatabaseSyncLike, stuckBefore: string, transcriptFloor: string): CompactionCounts;
+export interface TokenTally {
+    injected: number;
+    tokensSent: number;
+    tokensReread: number;
+}
+/** Memory blocks injected since `sinceIso`, the tokens they sent and the tokens later model calls re-read. */
+export declare function tokenTallySince(db: DatabaseSyncLike, sinceIso: string): TokenTally;
+//# sourceMappingURL=doctor-reads.d.ts.map

package/dist/store/doctor-reads.js

@@ -0,0 +1,19 @@
+/** Compaction records in all, those with a summary whose memories never got saved, and those still without a summary; each cutoff is an ISO time. */
+export function compactionCountsAt(db, stuckBefore, transcriptFloor) {
+    // SAFETY: COUNT aggregate row.
+    const row = db.prepare(`SELECT COUNT(*) AS total,
+              COUNT(CASE WHEN status = 'summarised' AND summarised_at < ? THEN 1 END) AS summarised,
+              COUNT(CASE WHEN status = 'started' AND started_at < ? AND started_at > ? AND transcript_path IS NOT NULL THEN 1 END) AS started
+       FROM compactions`).get(stuckBefore, stuckBefore, transcriptFloor);
+    return { total: Number(row?.total ?? 0), summarised: Number(row?.summarised ?? 0), started: Number(row?.started ?? 0) };
+}
+/** Memory blocks injected since `sinceIso`, the tokens they sent and the tokens later model calls re-read. */
+export function tokenTallySince(db, sinceIso) {
+    // SAFETY: COUNT/SUM aggregate row.
+    const row = db.prepare(`SELECT COUNT(CASE WHEN event = 'inject' THEN 1 END) AS n,
+              COALESCE(SUM(CASE WHEN event = 'inject' THEN tokens END), 0) AS t,
+              COALESCE(SUM(CASE WHEN event = 'reread' THEN tokens END), 0) AS r
+       FROM token_ledger WHERE ts >= ?`).get(sinceIso);
+    return { injected: Number(row?.n ?? 0), tokensSent: Number(row?.t ?? 0), tokensReread: Number(row?.r ?? 0) };
+}
+//# sourceMappingURL=doctor-reads.js.map

package/dist/store/dormant.d.ts

@@ -0,0 +1,105 @@
+/** Dormant memories: what sleep does with a faded memory instead of deleting it (config `dormant.enabled`; `retentionDays` bounds how long one is kept).
+ * Content stays in `dormant_memories` (schema v44) and the `memories` row goes, so every reader of `memories` stops seeing it, as if deleted.
+ * Not the raw archive (`raw_archive`, `archiveRawMemory`), which keeps metadata only. db-taking helpers leave the handle and transaction to the caller. */
+import { type DatabaseSyncLike } from '../db/index.js';
+import type { MemoryEntry } from '../core/memory.js';
+import type { SqlFragment } from './recall-scope.js';
+import type { WriteBudget } from '../util/write-budget.js';
+/** Why a memory went dormant: sleep's decay pass, an imported agent memory whose note was deleted, `hippo projects repair`
+ * splitting a two-project merge, or `hippo audit repair` setting aside an automatic memory with a certain defect. */
+export type DormantReason = 'decay' | 'source-deleted' | 'project-repair' | 'quality-repair';
+/** 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: one of the {@link DormantReason} values. */
+    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`; the caller deletes the `memories` row in the same transaction. */
+export declare function insertDormantRow(db: DatabaseSyncLike, move: DormantMove): void;
+/** A dormant memory's stored snapshot plus when and why it went dormant. */
+export interface DormantSnapshot {
+    entry: MemoryEntry;
+    reason: string;
+    strength: number;
+    dormantAt: string;
+}
+/** A tenant's stored dormant snapshot, or null when it has none with that id (another tenant's id reads as absent). */
+export declare function readDormantSnapshot(db: DatabaseSyncLike, tenantId: string, id: string): DormantSnapshot | null;
+/** Every dormant memory of a tenant whose snapshot still reads back. */
+export declare function listDormantSnapshots(db: DatabaseSyncLike, tenantId: string): DormantSnapshot[];
+/** Readable snapshots whose entry's source starts with `prefix`; a malformed snapshot is passed over, not an error. */
+export declare function dormantSnapshotsBySourcePrefix(db: DatabaseSyncLike, tenantId: string, prefix: string): DormantSnapshot[];
+/** Put `entry` in place of a tenant's dormant memory `id`, keeping when and why that one went dormant. */
+export declare function replaceDormantEntry(db: DatabaseSyncLike, tenantId: string, id: string, entry: MemoryEntry): void;
+/** Delete a tenant's dormant memory. Returns false when there was none. */
+export declare function deleteDormantRow(db: DatabaseSyncLike, tenantId: string, id: string): boolean;
+/** Deletes the tenant's dormant copies of a rejected digest whose snapshot scope `inReach` admits, so the value cannot linger; returns their ids. */
+export declare function purgeDormantByDigest(db: DatabaseSyncLike, tenantId: string, digest: string, inReach: (scope: string | null) => boolean): string[];
+/** Deletes for good every memory that went dormant before `cutoffIso`, on one handle; returns how many went, or under `dryRun` how many would. */
+export declare function expireDormantBefore(hippoRoot: string, cutoffIso: string, opts: {
+    dryRun: boolean;
+    budget: WriteBudget;
+    busyWaitMs: number;
+}): Promise<number>;
+/** A tenant's dormant memories whose scope `admit` passes, newest first, read on a handle of its own. */
+export declare function loadDormantMemories(hippoRoot: string, tenantId: string, opts?: ListDormantOpts, admit?: SqlFragment): DormantMemory[];
+/** Whether a tenant holds a dormant memory with this id whose scope `admit` passes, read on a handle of its own. */
+export declare function holdsDormantMemory(hippoRoot: string, tenantId: string, id: string, admit?: SqlFragment): boolean;
+/** One restore as the store applies it. The two functions are the caller's policy over plain rows; neither is handed the handle. */
+export interface DormantRestore {
+    readonly tenantId: string;
+    readonly id: string;
+    /** Who restores, for the audit rows. */
+    readonly actor: string;
+    /** False for a snapshot this caller may not touch, which then reads as missing. */
+    readonly inReach: (scope: string | null) => boolean;
+    /** The live memory the snapshot comes back as at `now`; a throw refuses before any write. */
+    readonly revive: (snapshot: DormantSnapshot, now: Date) => MemoryEntry;
+}
+/** The restored memory, or why nothing was written: no dormant copy in reach, or a live memory already holds the id. */
+export type DormantRestoreOutcome = {
+    readonly status: 'restored';
+    readonly entry: MemoryEntry;
+} | {
+    readonly status: 'missing';
+} | {
+    readonly status: 'active';
+};
+/** Brings one dormant memory back on a single handle: the live row, the dormant delete and the audit row commit together, then its mirrors are written. */
+export declare function restoreDormantMemory(hippoRoot: string, restore: DormantRestore): DormantRestoreOutcome;
+/** One permanent delete of a dormant memory. */
+export interface DormantForget {
+    readonly tenantId: string;
+    readonly id: string;
+    /** Who forgets, for the audit row. */
+    readonly actor: string;
+    /** The scopes this caller may touch; a row outside them reads as missing. */
+    readonly admit: SqlFragment;
+}
+/** Deletes a tenant's dormant memory for good and writes its `forget` audit row, on a single handle; false when it holds none `admit` passes. */
+export declare function forgetDormantMemory(hippoRoot: string, forget: DormantForget): boolean;
+//# sourceMappingURL=dormant.d.ts.map

package/dist/store/dormant.js

@@ -0,0 +1,241 @@
+/** Dormant memories: what sleep does with a faded memory instead of deleting it (config `dormant.enabled`; `retentionDays` bounds how long one is kept).
+ * Content stays in `dormant_memories` (schema v44) and the `memories` row goes, so every reader of `memories` stops seeing it, as if deleted.
+ * Not the raw archive (`raw_archive`, `archiveRawMemory`), which keeps metadata only. db-taking helpers leave the handle and transaction to the caller. */
+import { closeHippoDb, openHippoDb, withWriteScope, withWriteScopeOr } from '../db/index.js';
+import { onHandle } from './open.js';
+import { RejectedValueError, rejectionDigest } from './rejection.js';
+import { escapeLike } from '../util/escape.js';
+import { warnDamagedColumn } from '../util/stored-json.js';
+import { DAY_MS } from '../util/time.js';
+import { appendAuditEvent } from './audit.js';
+import { audit, auditRejectionRefusal } from './audit-event.js';
+import { entryIdTakenAt } from './entry-reads.js';
+import { writeEntryDbOnly, writeEntryMirrors } from './entry-writes.js';
+const DEFAULT_LIST_LIMIT = 20;
+/** Insert (or refresh) the dormant snapshot for `move.entry`; the caller deletes the `memories` row in the same transaction. */
+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);
+}
+/** Parse a stored snapshot back into a MemoryEntry, or null when the row no longer matches it (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 {
+        // A row that will not parse is out of shape, so it is not restorable.
+        warnDamagedColumn({ table: 'dormant_memories', id: row.id, column: 'entry_json' }, 'not valid JSON');
+        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,
+    };
+}
+// The snapshot's scope as a `scope` column, so recall-scope's SQL fragments read it as they read memories.scope.
+const DORMANT_WITH_SCOPE = `(SELECT *, CASE WHEN json_valid(entry_json) THEN json_extract(entry_json, '$.scope') END AS scope FROM dormant_memories)`;
+const EVERY_SCOPE = { sql: '1', params: [] };
+/** A tenant's dormant memories whose scope `admit` passes, newest first, optionally filtered by search terms. */
+function listDormantRows(db, tenantId, opts = {}, admit = EVERY_SCOPE) {
+    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_WITH_SCOPE}
+      WHERE tenant_id = ? AND ${admit.sql}${termClauses}
+      ORDER BY dormant_at DESC, id ASC
+      LIMIT ?`).all(tenantId, ...admit.params, ...terms.map((t) => `%${escapeLike(t)}%`), limit);
+    return rows.map(rowToDormantMemory);
+}
+/** A tenant's stored dormant snapshot, or null when it has none 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);
+    return row ? toSnapshot(row) : null;
+}
+/** Every dormant memory of a tenant whose snapshot still reads back. */
+export function listDormantSnapshots(db, tenantId) {
+    // 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 = ?`).all(tenantId);
+    return rows.flatMap((row) => toSnapshot(row) ?? []);
+}
+/** Readable snapshots whose entry's source starts with `prefix`; a malformed snapshot is passed over, not an error. */
+export function dormantSnapshotsBySourcePrefix(db, tenantId, prefix) {
+    // 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 = ?
+        AND CASE WHEN json_valid(entry_json) THEN json_extract(entry_json, '$.source') END LIKE ? ESCAPE '\\'`).all(tenantId, `${escapeLike(prefix)}%`);
+    return rows.flatMap((row) => toSnapshot(row) ?? []).filter((s) => String(s.entry.source).startsWith(prefix));
+}
+function toSnapshot(row) {
+    const entry = parseSnapshot(row);
+    return entry ? { entry, reason: row.reason, strength: row.strength, dormantAt: row.dormant_at } : null;
+}
+/** Put `entry` in place of a tenant's dormant memory `id`, keeping when and why that one went dormant. */
+export function replaceDormantEntry(db, tenantId, id, entry) {
+    db.prepare(`UPDATE dormant_memories SET id = ?, content = ?, entry_json = ? WHERE tenant_id = ? AND id = ?`)
+        .run(entry.id, entry.content, JSON.stringify(entry), tenantId, id);
+}
+/** Whether a tenant has a dormant memory with this id whose scope `admit` passes (snapshot readable or not). */
+function hasDormantRow(db, tenantId, id, admit = EVERY_SCOPE) {
+    return db.prepare(`SELECT 1 FROM ${DORMANT_WITH_SCOPE} WHERE tenant_id = ? AND id = ? AND ${admit.sql}`).get(tenantId, id, ...admit.params) !== 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;
+}
+/** Deletes the tenant's dormant copies of a rejected digest whose snapshot scope `inReach` admits, so the value cannot linger; returns their ids. */
+export function purgeDormantByDigest(db, tenantId, digest, inReach) {
+    // SAFETY: rows' shape matches the three columns named in the SELECT.
+    const rows = db.prepare(`SELECT id, content, CASE WHEN json_valid(entry_json) THEN json_extract(entry_json, '$.scope') END AS scope
+       FROM dormant_memories WHERE tenant_id = ?`).all(tenantId);
+    const removed = [];
+    for (const row of rows) {
+        if (rejectionDigest(row.content) !== digest || !inReach(row.scope))
+            continue;
+        deleteDormantRow(db, tenantId, row.id);
+        removed.push(row.id);
+    }
+    return removed;
+}
+function expiredDormantKeys(db, cutoffIso) {
+    const sql = `SELECT tenant_id AS tenantId, id FROM dormant_memories WHERE dormant_at < ?`;
+    // SAFETY: rows' shape matches the two columns named in the SELECT.
+    return db.prepare(sql).all(cutoffIso);
+}
+function deleteExpiredDormantRow(db, key, cutoffIso) {
+    const sql = `DELETE FROM dormant_memories WHERE tenant_id = ? AND id = ? AND dormant_at < ?`;
+    return Number(db.prepare(sql).run(key.tenantId, key.id, cutoffIso).changes ?? 0);
+}
+/** Deletes `keys` in transactions of about `budget.holdMs`, letting other writers in between; returns how many went. */
+async function expireInChunks(db, keys, cutoffIso, budget) {
+    let gone = 0;
+    let next = 0;
+    let committedAt = 0;
+    while (next < keys.length) {
+        if (next > 0)
+            await budget.pause(committedAt);
+        withWriteScope(db, 'expire_dormant_chunk', () => {
+            const begunAt = budget.clock();
+            do
+                gone += deleteExpiredDormantRow(db, keys[next++], cutoffIso);
+            while (next < keys.length && budget.clock() - begunAt < budget.holdMs);
+        });
+        committedAt = budget.clock();
+    }
+    return gone;
+}
+/** Deletes for good every memory that went dormant before `cutoffIso`, on one handle; returns how many went, or under `dryRun` how many would. */
+export async function expireDormantBefore(hippoRoot, cutoffIso, opts) {
+    const db = openHippoDb(hippoRoot, { busyWaitMs: opts.busyWaitMs });
+    try {
+        // The keys come from a read, so a run with nothing to expire never takes the write lock.
+        const keys = expiredDormantKeys(db, cutoffIso);
+        return opts.dryRun ? keys.length : await expireInChunks(db, keys, cutoffIso, opts.budget);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** A tenant's dormant memories whose scope `admit` passes, newest first, read on a handle of its own. */
+export function loadDormantMemories(hippoRoot, tenantId, opts = {}, admit = EVERY_SCOPE) {
+    return onHandle(hippoRoot, (db) => {
+        return listDormantRows(db, tenantId, opts, admit);
+    });
+}
+/** Whether a tenant holds a dormant memory with this id whose scope `admit` passes, read on a handle of its own. */
+export function holdsDormantMemory(hippoRoot, tenantId, id, admit = EVERY_SCOPE) {
+    return onHandle(hippoRoot, (db) => {
+        return hasDormantRow(db, tenantId, id, admit);
+    });
+}
+function auditDormantRestore(db, restore, snapshot, now) {
+    appendAuditEvent(db, {
+        tenantId: restore.tenantId,
+        actor: restore.actor,
+        op: 'dormant_restore',
+        targetId: restore.id,
+        metadata: {
+            reason: snapshot.reason,
+            strengthAtDormancy: snapshot.strength,
+            dormantAt: snapshot.dormantAt,
+            daysDormant: Math.max(0, (now.getTime() - Date.parse(snapshot.dormantAt)) / DAY_MS),
+        },
+    });
+}
+function restoreInWriteScope(db, restore) {
+    return withWriteScopeOr(db, 'restore_dormant', (rollback) => {
+        const snapshot = readDormantSnapshot(db, restore.tenantId, restore.id);
+        if (!snapshot || !restore.inReach(snapshot.entry.scope ?? null))
+            return rollback({ status: 'missing' });
+        if (entryIdTakenAt(db, restore.id))
+            return rollback({ status: 'active' });
+        const now = new Date();
+        const entry = restore.revive(snapshot, now);
+        writeEntryDbOnly(db, entry, { actor: restore.actor });
+        deleteDormantRow(db, restore.tenantId, restore.id);
+        // A restore is a labelled "forgot it, then needed it" event, the signal a learned lifecycle trains on.
+        // Same write scope as the restore, so the label exists exactly when the restore does.
+        auditDormantRestore(db, restore, snapshot, now);
+        return { status: 'restored', entry };
+    });
+}
+/** Brings one dormant memory back on a single handle: the live row, the dormant delete and the audit row commit together, then its mirrors are written. */
+export function restoreDormantMemory(hippoRoot, restore) {
+    return onHandle(hippoRoot, (db) => {
+        let outcome;
+        try {
+            outcome = restoreInWriteScope(db, restore);
+        }
+        catch (error) {
+            // Written after the rollback, so the refusal row outlives it.
+            if (error instanceof RejectedValueError)
+                auditRejectionRefusal(db, error, restore.actor);
+            throw error;
+        }
+        if (outcome.status === 'restored')
+            writeEntryMirrors(hippoRoot, outcome.entry);
+        return outcome;
+    });
+}
+/** Deletes a tenant's dormant memory for good and writes its `forget` audit row, on a single handle; false when it holds none `admit` passes. */
+export function forgetDormantMemory(hippoRoot, forget) {
+    const { tenantId, id, actor, admit } = forget;
+    return onHandle(hippoRoot, (db) => {
+        if (!hasDormantRow(db, tenantId, id, admit) || !deleteDormantRow(db, tenantId, id))
+            return false;
+        // Best-effort, like every other forget audit row: the delete stands.
+        audit(db, 'forget', { tenantId, actor, targetId: id, metadata: { dormant: true } });
+        return true;
+    });
+}
+//# sourceMappingURL=dormant.js.map

package/dist/store/embeddings/index.d.ts

@@ -0,0 +1,36 @@
+/** Optional embedding-based semantic search for Hippo.
+ * Uses @huggingface/transformers (local, no API keys, ~22MB model); falls back silently if not installed. */
+import { MemoryEntry } from '../../core/memory.js';
+import { EMBEDDING_MODEL_META_KEY } from '../../db/vector-store.js';
+import { type EmbeddingProvider } from './provider.js';
+import type { HippoStore } from '../index.js';
+export { EMBEDDING_MODEL_META_KEY };
+/** Bump when `embeddingInputText` changes existing vectors; folded into the stored index identity (`embeddingIndexIdentity`) so it reindexes like a model
+ * change. Format 2 = `path:*` tags excluded; format 1 (implicit, no suffix) included them. */
+export declare const EMBED_TEXT_FORMAT = 2;
+/** Stored-index identity for a provider id: folds `EMBED_TEXT_FORMAT` in so a model or text-format change invalidates the index. The ONE choke point for
+ * compare (`embeddingModelRequiresReindex`) and save (`saveStoredEmbeddingModel`); they MUST version identically or every call reindexes. */
+export declare function embeddingIndexIdentity(providerId: string): string;
+/** Text embedded for an entry: content plus tags, space-joined and trimmed, minus `path:*` tags.
+ * `path:*` tags derive from cwd, so identical content would embed differently per store location; path relevance is handled by `pathOverlapScore`. */
+export declare function embeddingInputText(entry: {
+    content: string;
+    tags: string[];
+}): string;
+/** Persist the stored-index identity for `model` (see `embeddingIndexIdentity`); versioning happens here, not at call sites,
+ * and must stay consistent with the compare side in `embeddingModelRequiresReindex`. */
+export declare function saveStoredEmbeddingModel(hippoRoot: string, model: string): void;
+/** The one rebuild rule every store applies to its indexed model. */
+export declare function indexNeedsRebuild(indexed: string | null, providerId: string): boolean;
+export declare function resolveIndexedEmbeddingModel(hippoRoot: string, index?: Record<string, number[]>): string | null;
+export declare function embeddingModelRequiresReindex(hippoRoot: string, model: string, index?: Record<string, number[]>): boolean;
+/** Cosine similarity; handles unnormalized vectors, returns 0 for empty or mismatched vectors. */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+/** `cosineSimilarity` over any indexable vectors; a Float32 view reads the same doubles as its number[] copy, so the score is the same. */
+export declare function cosineOf(a: ArrayLike<number>, b: ArrayLike<number>): number;
+/** Embed a single memory entry and cache the result in the embedding index; with `store`, through its vectorWrites, never opening hippo.db. */
+export declare function embedMemory(hippoRoot: string, entry: MemoryEntry, model?: string, store?: HippoStore): Promise<void>;
+/** Embeds every entry with no cached vector, prunes vectors of deleted memories, and returns how many it embedded; `provider` defaults to the
+ *  configured one. With `store`, every tenant's memories with no vector for the provider's model go through its `vectorWrites`, never hippo.db. */
+export declare function embedAll(hippoRoot: string, model?: string, provider?: EmbeddingProvider, store?: HippoStore): Promise<number>;
+//# sourceMappingURL=index.d.ts.map