hippo-memory 1.44.0 → 1.46.0

package/dist/store.js

@@ -6,12 +6,13 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { Layer, generateId } from './memory.js';
+import { Layer, generateId, AUTO_DELETABLE_SQL, DEFAULT_HALF_LIFE_DAYS } from './memory.js';
 import { dumpFrontmatter, parseFrontmatter } from './yaml.js';
 import { openHippoDb, closeHippoDb, getMeta, setMeta, isFtsAvailable, pruneConsolidationRuns, getHippoDbPath, } from './db.js';
 import { rowToSessionHandoff, isHandoffOutcome } from './handoff.js';
 import { CARD_TRANSITIONS, CARD_LEASE_MS } from './card.js';
-import { tokenize } from './search.js';
+import { tokenize, markRetrieved } from './search.js';
+import { isRecallBoostAblated } from './ablation.js';
 import { appendAuditEvent } from './audit.js';
 import { resolveTenantId } from './tenant.js';
 import { deriveOriginProject, originFromSource, findHippoStoreDir, realpathOrResolve } from './project-identity.js';
@@ -22,6 +23,7 @@ import { checkRejectionGuard, RejectedValueError, rejectionDigest, normalizeValu
 // inside function bodies (never at module-evaluation time), so the cycle
 // is the standard safe mutual-function-reference shape under NodeNext ESM.
 import { archiveRawMemory } from './raw-archive.js';
+import { insertDormantRow } from './dormant.js';
 /**
  * Emit an audit event for a mutation against `db`. Wrapped so a broken audit
  * log can never crash the surrounding mutation — the SQLite store is still the
@@ -118,11 +120,27 @@ export function initStore(hippoRoot) {
         if (bootstrapped) {
             syncMirrorFiles(hippoRoot, db);
         }
+        recordHalfLifeBaseForNewStore(db);
     }
     finally {
         closeHippoDb(db);
     }
 }
+/** `meta` key holding the default half-life base a store's memories are on (src/half-life-migration.ts). */
+export const HALF_LIFE_BASE_META_KEY = 'default_half_life_base';
+/**
+ * A store with no memories starts on the current default half-life base, so
+ * `hippo sleep` never migrates it. A store that already holds memories and
+ * no recorded base predates the record, and keeps reading as the legacy
+ * 7-day base until sleep migrates it.
+ */
+function recordHalfLifeBaseForNewStore(db) {
+    if (getMeta(db, HALF_LIFE_BASE_META_KEY, '') !== '')
+        return;
+    if (db.prepare(`SELECT 1 AS x FROM memories LIMIT 1`).get() !== undefined)
+        return;
+    setMeta(db, HALF_LIFE_BASE_META_KEY, String(DEFAULT_HALF_LIFE_DAYS));
+}
 function ensureMirrorDirectories(hippoRoot) {
     const dirs = [
         hippoRoot,
@@ -504,7 +522,7 @@ function canonicalConflictPair(aId, bId) {
         ? { memory_a_id: aId, memory_b_id: bId }
         : { memory_a_id: bId, memory_b_id: aId };
 }
-function loadSearchRows(db, query, limit, tenantId, scopeFilter) {
+function loadSearchRows(db, query, limit, tenantId, scopeFilter, includeSuperseded = true) {
     // tenantId undefined = no tenant filter (legacy callers / cross-deployment
     // helpers). tenantId set = strict tenant isolation, leveraging the composite
     // idx_memories_tenant_created (leading column tenant_id, O(log n) lookup).
@@ -597,13 +615,15 @@ function loadSearchRows(db, query, limit, tenantId, scopeFilter) {
             scopeParams.push(scopeFilter.value);
         }
     }
+    const currentAlias = includeSuperseded ? '' : ' AND m.superseded_by IS NULL';
+    const currentNoAlias = includeSuperseded ? '' : ' AND superseded_by IS NULL';
     const terms = Array.from(new Set(tokenize(query)));
     if (terms.length === 0) {
         // F3 (v1.7.0) self-review: empty-query path is the second uncapped
         // path (codex diff-pass caught the full-store fallback at the bottom;
         // this no-terms path had the same shape). Apply LIMIT so all four
         // candidate paths honour the caller's cap when set.
-        const sql = `SELECT ${MEMORY_SELECT_COLUMNS} FROM memories${tenantOnlyPredicate}${archivedClauseTenantOnly}${scopeClauseTenantOnly} ORDER BY created ASC, id ASC LIMIT ?`;
+        const sql = `SELECT ${MEMORY_SELECT_COLUMNS} FROM memories${tenantOnlyPredicate}${archivedClauseTenantOnly}${scopeClauseTenantOnly}${currentNoAlias} ORDER BY created ASC, id ASC LIMIT ?`;
         // SAFETY: sql selects exactly MEMORY_SELECT_COLUMNS, whose column list
         // matches MemoryRow's field set.
         return db.prepare(sql).all(...tenantParams, ...scopeParams, limit);
@@ -630,7 +650,7 @@ function loadSearchRows(db, query, limit, tenantId, scopeFilter) {
         SELECT ${MEMORY_SEARCH_COLUMNS}
         FROM memories m
         JOIN memories_fts f ON f.id = m.id
-        WHERE memories_fts MATCH ?${tenantPredicate}${archivedClauseAlias}${scopeClauseAlias}
+        WHERE memories_fts MATCH ?${tenantPredicate}${archivedClauseAlias}${scopeClauseAlias}${currentAlias}
         ORDER BY bm25(memories_fts), m.updated_at DESC, m.content ASC, m.id ASC
         LIMIT ?
       `).all(ftsQuery, ...tenantParams, ...scopeParams, limit);
@@ -652,7 +672,7 @@ function loadSearchRows(db, query, limit, tenantId, scopeFilter) {
     const rows = db.prepare(`
     SELECT ${MEMORY_SELECT_COLUMNS}
     FROM memories
-    WHERE (${where})${tenantPredicateNoAlias}${archivedClauseNoAlias}${scopeClauseNoAlias}
+    WHERE (${where})${tenantPredicateNoAlias}${archivedClauseNoAlias}${scopeClauseNoAlias}${currentNoAlias}
     ORDER BY updated_at DESC, created DESC, content ASC, id ASC
     LIMIT ?
   `).all(...params, ...tenantParams, ...scopeParams, limit);
@@ -663,7 +683,7 @@ function loadSearchRows(db, query, limit, tenantId, scopeFilter) {
     // now reported on RecallResult, an unbounded fallback would lie about
     // candidate-pool size. Apply LIMIT here so all four paths honour the
     // caller's cap.
-    const fallback = `SELECT ${MEMORY_SELECT_COLUMNS} FROM memories${tenantOnlyPredicate}${archivedClauseTenantOnly}${scopeClauseTenantOnly} ORDER BY created ASC, id ASC LIMIT ?`;
+    const fallback = `SELECT ${MEMORY_SELECT_COLUMNS} FROM memories${tenantOnlyPredicate}${archivedClauseTenantOnly}${scopeClauseTenantOnly}${currentNoAlias} ORDER BY created ASC, id ASC LIMIT ?`;
     // SAFETY: fallback selects exactly MEMORY_SELECT_COLUMNS, matching
     // MemoryRow's field set.
     return db.prepare(fallback).all(...tenantParams, ...scopeParams, limit);
@@ -1064,18 +1084,28 @@ function buildStatsFromDb(db) {
  * `buildIndexFromDb`'s query.
  */
 export function writeIndexMirror(hippoRoot, index) {
-    fs.writeFileSync(path.join(hippoRoot, 'index.json'), JSON.stringify(index, null, 2), 'utf8');
+    mirrorBestEffort('index.json', () => fs.writeFileSync(path.join(hippoRoot, 'index.json'), JSON.stringify(index, null, 2), 'utf8'));
 }
 function writeStatsMirror(hippoRoot, stats) {
-    fs.writeFileSync(path.join(hippoRoot, 'stats.json'), JSON.stringify(stats, null, 2), 'utf8');
+    mirrorBestEffort('stats.json', () => fs.writeFileSync(path.join(hippoRoot, 'stats.json'), JSON.stringify(stats, null, 2), 'utf8'));
+}
+/** Mirrors are derived from SQLite and written after COMMIT, so a failed write warns instead of failing a committed change. */
+function mirrorBestEffort(what, write) {
+    try {
+        write();
+    }
+    catch (err) {
+        console.error(`hippo: ${what} not refreshed (${err instanceof Error ? err.message : String(err)}); the database write succeeded`);
+    }
 }
 function syncMirrorFiles(hippoRoot, db) {
     // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
     // MemoryRow's field set.
     const entries = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories ORDER BY created ASC, id ASC`).all();
-    for (const entry of entries.map(rowToEntry)) {
-        writeMarkdownMirror(hippoRoot, entry);
-    }
+    mirrorBestEffort('markdown mirrors', () => {
+        for (const entry of entries.map(rowToEntry))
+            writeMarkdownMirror(hippoRoot, entry);
+    });
     // SAFETY: conflicts' shape matches the eight columns named in the SELECT
     // above.
     const conflicts = db.prepare(`
@@ -1084,20 +1114,16 @@ function syncMirrorFiles(hippoRoot, db) {
     WHERE status = 'open'
     ORDER BY updated_at DESC, id DESC
   `).all();
-    writeConflictMirrors(hippoRoot, conflicts.map(rowToMemoryConflict));
+    mirrorBestEffort('conflict mirrors', () => writeConflictMirrors(hippoRoot, conflicts.map(rowToMemoryConflict)));
     writeIndexMirror(hippoRoot, buildIndexFromDb(db));
     writeStatsMirror(hippoRoot, buildStatsFromDb(db));
 }
-/**
- * Load the current derived index from SQLite and refresh the mirror file.
- */
+/** Load the derived index from SQLite. Read-only: writers refresh index.json, so readers never race on it. */
 export function loadIndex(hippoRoot) {
     initStore(hippoRoot);
     const db = openHippoDb(hippoRoot);
     try {
-        const index = buildIndexFromDb(db);
-        writeIndexMirror(hippoRoot, index);
-        return index;
+        return buildIndexFromDb(db);
     }
     finally {
         closeHippoDb(db);
@@ -1267,7 +1293,7 @@ export function writeEntryDbOnly(db, entry, opts) {
  * during a tx that subsequently rolls back would leave orphan markdown.
  */
 export function writeEntryMirrors(hippoRoot, db, entry) {
-    writeMarkdownMirror(hippoRoot, entry);
+    mirrorBestEffort(`${entry.id}.md`, () => writeMarkdownMirror(hippoRoot, entry));
     writeIndexMirror(hippoRoot, buildIndexFromDb(db));
 }
 /**
@@ -1320,6 +1346,46 @@ export function loadEntriesByIds(hippoRoot, ids, tenantId) {
         closeHippoDb(db);
     }
 }
+/** Strengthen what a read returned: update only the four retrieval columns on the live row, never a stale copy.
+ *  Best effort: a failure logs and never fails the read. Returns the ids found in this store. */
+export function strengthenRetrieved(hippoRoot, ids, tenantId) {
+    const found = new Set();
+    if (ids.length === 0 || isRecallBoostAblated())
+        return found;
+    let db;
+    try {
+        db = openHippoDb(hippoRoot);
+        db.exec('BEGIN IMMEDIATE');
+        const tenantClause = tenantId !== undefined ? ' AND tenant_id = ?' : '';
+        const select = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id = ?${tenantClause}`);
+        const live = [];
+        for (const id of ids) {
+            // SAFETY: the SELECT names exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
+            const row = (tenantId !== undefined ? select.get(id, tenantId) : select.get(id));
+            if (row)
+                live.push(rowToEntry(row));
+        }
+        const update = db.prepare('UPDATE memories SET retrieval_count = ?, last_retrieved = ?, half_life_days = ?, strength = ? WHERE id = ?');
+        for (const e of markRetrieved(live)) {
+            update.run(e.retrieval_count, e.last_retrieved, e.half_life_days, e.strength, e.id);
+            found.add(e.id);
+        }
+        db.exec('COMMIT');
+    }
+    catch (error) {
+        try {
+            db?.exec('ROLLBACK');
+        }
+        catch { /* already rolled back; keep the original error */ }
+        console.error(`hippo: retrieval stats not saved (${error instanceof Error ? error.message : String(error)})`);
+        found.clear();
+    }
+    finally {
+        if (db)
+            closeHippoDb(db);
+    }
+    return found;
+}
 /**
  * All `kind='raw'` rows for a given session, tenant-scoped, returned
  * oldest-first. Used by `api.assemble` to walk a session's chronological
@@ -1499,8 +1565,8 @@ export function loadChildrenOf(hippoRoot, parentId, tenantId) {
  * removed) and `resolveConflict` (`conflict_resolve` row per resolution).
  * Default keeps `deleteEntry` byte-identical to its pre-split behavior.
  *
- * Returns `{tenantId, dagParentId}` for the removed row, or `null` if no row
- * with `id` existed.
+ * Returns `{tenantId, dagParentId}` for the removed row, or `null` if no row with `id`
+ * existed or `automatic` refused it (pinned or raw at DELETE time, so a late pin wins).
  */
 export function deleteEntryCore(db, id, opts) {
     // SAFETY: row's shape matches the three columns named in the SELECT above.
@@ -1509,10 +1575,12 @@ export function deleteEntryCore(db, id, opts) {
         .get(id);
     if (!row?.id)
         return null;
-    db.prepare(`DELETE FROM memories WHERE id = ?`).run(id);
+    const guard = opts?.automatic ? ` AND ${AUTO_DELETABLE_SQL}` : '';
+    if (Number(db.prepare(`DELETE FROM memories WHERE id = ?${guard}`).run(id).changes ?? 0) === 0)
+        return null;
     deleteFtsRow(db, id);
     if (!opts?.suppressForgetAudit) {
-        audit(db, 'forget', id, undefined, opts?.actor ?? 'cli', row.tenant_id);
+        audit(db, 'forget', id, opts?.reason ? { reason: opts.reason } : undefined, opts?.actor ?? 'cli', row.tenant_id);
     }
     // v0.30 / E2 — DAG live-coupling: forget of a child under a level-2
     // summary marks parent dirty. Non-atomic with the DELETE (no SAVEPOINT
@@ -1542,7 +1610,7 @@ export function deleteEntry(hippoRoot, id, opts) {
         const result = deleteEntryCore(db, id, opts);
         if (!result)
             return false;
-        removeEntryMirrors(hippoRoot, id);
+        purgeMirrorBestEffort(hippoRoot, id, false, 'deleteEntry');
         writeIndexMirror(hippoRoot, buildIndexFromDb(db));
         return true;
     }
@@ -1550,13 +1618,28 @@ export function deleteEntry(hippoRoot, id, opts) {
         closeHippoDb(db);
     }
 }
-/**
- * Batch-write and batch-delete entries in a single transaction.
- * Used by consolidation to avoid N open/close cycles.
- */
-export function batchWriteAndDelete(hippoRoot, toWrite, toDeleteIds) {
-    if (toWrite.length === 0 && toDeleteIds.length === 0)
-        return;
+// The child fields a level-2/3 summary is built from (loadChildrenOfSummary, generateDagSummary).
+const SUMMARY_INPUTS = ['content', 'created', 'dag_parent_id', 'kind'];
+function mergeOwnChanges(base, ours, live) {
+    const row = { ...live };
+    const loaded = new Map(Object.entries(base));
+    for (const [key, value] of Object.entries(ours)) {
+        if (JSON.stringify(value) !== JSON.stringify(loaded.get(key)))
+            Object.assign(row, { [key]: value });
+    }
+    return row;
+}
+/** Consolidation's flush, one transaction. With `snapshot` (rows as the caller loaded them), a write keeps only
+ *  the fields the caller changed, takes the rest from the live row, and never resurrects a row that is gone.
+ *
+ *  `dormant` (src/dormant.ts): each move's snapshot is inserted into `dormant_memories` and its `memories` row
+ *  leaves exactly like a delete (FTS row, DAG parent dirty-mark, mirrors), in the same transaction, so a memory
+ *  is never in both places or in neither. Deletes and moves both skip rows that are no longer auto-deletable
+ *  (pinned or raw since the caller decided). Returns the ids that left `memories`, deleted or moved. */
+export function batchWriteAndDelete(hippoRoot, toWrite, toDeleteIds, opts) {
+    const dormantMoves = opts?.dormant ?? [];
+    if (toWrite.length === 0 && toDeleteIds.length === 0 && dormantMoves.length === 0)
+        return [];
     initStore(hippoRoot);
     const db = openHippoDb(hippoRoot);
     try {
@@ -1576,23 +1659,23 @@ export function batchWriteAndDelete(hippoRoot, toWrite, toDeleteIds) {
         // dirty for the dominant mutation source (decay, merge, garbage-collect).
         const dirtyParents = new Set();
         const tenantById = new Map();
+        const deletableIds = [];
         if (toDeleteIds.length > 0) {
             const placeholders = toDeleteIds.map(() => '?').join(',');
-            // SAFETY: rows' shape matches the two columns named in the SELECT
-            // above.
-            const rows = db.prepare(`SELECT dag_parent_id, tenant_id FROM memories WHERE id IN (${placeholders})`).all(...toDeleteIds);
+            // A row pinned after the caller decided to delete it survives.
+            // SAFETY: rows' shape matches the three columns named in the SELECT.
+            const rows = db.prepare(`SELECT id, dag_parent_id, tenant_id FROM memories WHERE id IN (${placeholders}) AND ${AUTO_DELETABLE_SQL}`).all(...toDeleteIds);
             for (const row of rows) {
+                deletableIds.push(row.id);
                 if (row.dag_parent_id) {
                     dirtyParents.add(row.dag_parent_id);
                     tenantById.set(row.dag_parent_id, row.tenant_id ?? 'default');
                 }
             }
         }
-        // v39: consolidate's new semantic rows (and any other batch writer)
-        // bypass writeEntry, so stamp store-derived origins here too - a NULL
-        // origin would make freshly consolidated memories vanish from ambient
-        // context (codex gating review P1).
-        const stampedWrites = toWrite.map((e) => stampOriginProject(hippoRoot, e));
+        // v39: batch writers bypass writeEntry, so stamp store-derived origins here too (a NULL origin hides new
+        // memories from ambient context). A row queued twice keeps only its last version, the one the merge compares.
+        const stampedWrites = [...new Map(toWrite.map((e) => [e.id, stampOriginProject(hippoRoot, e)])).values()];
         // AT1 P1 fix (codex, batch-transaction rejection race): the producer-side
         // check (e.g. consolidate.ts's merge pass) runs BEFORE this transaction,
         // on a different connection. A `hippo reject X` that commits in that
@@ -1611,9 +1694,15 @@ export function batchWriteAndDelete(hippoRoot, toWrite, toDeleteIds) {
         // demotion/replay re-persist of a rejected-removed row means it stays
         // gone, which is the entire point of the tombstone.
         let batchRejectedSkips = 0;
-        const skippedWriteIds = new Set();
+        const written = [];
+        const readLiveRow = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id = ?`);
         for (const entry of stampedWrites) {
-            const entryTenantId = entry.tenantId ?? 'default';
+            const base = opts?.snapshot?.get(entry.id);
+            // SAFETY: MEMORY_SELECT_COLUMNS is the MemoryRow shape rowToEntry reads.
+            const liveRow = readLiveRow.get(entry.id);
+            const live = liveRow ? rowToEntry(liveRow) : undefined;
+            const row = base && live ? mergeOwnChanges(base, entry, live) : entry;
+            const entryTenantId = row.tenantId ?? 'default';
             // Codex delta-review P2 fix: reuse checkRejectionGuard rather than a
             // bare tombstone probe — the guard's content-INTRODUCTION
             // classification must apply here too. A tombstone can legitimately
@@ -1624,17 +1713,19 @@ export function batchWriteAndDelete(hippoRoot, toWrite, toDeleteIds) {
             // changes content TO the rejected value; unchanged same-id re-persists
             // pass through, exactly as on the writeEntry path.
             try {
-                checkRejectionGuard(db, entryTenantId, entry.id, entry.content);
+                checkRejectionGuard(db, entryTenantId, row.id, row.content);
             }
             catch (err) {
                 if (err instanceof RejectedValueError) {
                     batchRejectedSkips++;
-                    skippedWriteIds.add(entry.id);
-                    audit(db, 'reject_refusal', entry.id, { digest: err.digest, reason: err.reason }, 'sleep-batch', entryTenantId);
+                    audit(db, 'reject_refusal', row.id, { digest: err.digest, reason: err.reason }, 'sleep-batch', entryTenantId);
                     continue;
                 }
                 throw err;
             }
+            if (base && !live)
+                continue;
+            written.push(row);
             // AT1 (plan §3, corrected): bypass the rejection guard here.
             // Consolidation merges are DETERMINISTIC CONCATENATION (mergeContents,
             // consolidate.ts:736-751) of already-guarded leaf facts, not an LLM
@@ -1647,14 +1738,33 @@ export function batchWriteAndDelete(hippoRoot, toWrite, toDeleteIds) {
             // check and this COMMIT. The guard itself still belongs on leaf
             // inserts, which write through writeEntry / writeEntryDbOnly and stay
             // guarded (bypassRejectionGuard defaults false).
-            upsertEntryRow(db, entry, true);
-            // Hook for writes: child upserted under a level-2 summary marks parent dirty.
-            if (entry.dag_parent_id) {
-                dirtyParents.add(entry.dag_parent_id);
-                tenantById.set(entry.dag_parent_id, entry.tenantId);
+            upsertEntryRow(db, row, true);
+            // Hook for writes: a new child, or a change to what its summary reads, marks the parent dirty; decay alone does not.
+            if (row.dag_parent_id && (!live || SUMMARY_INPUTS.some((k) => row[k] !== live[k]))) {
+                dirtyParents.add(row.dag_parent_id);
+                tenantById.set(row.dag_parent_id, row.tenantId);
             }
         }
-        for (const id of toDeleteIds) {
+        // Dormant moves: same eligibility and DAG bookkeeping as deletes.
+        const movable = [];
+        if (dormantMoves.length > 0) {
+            const byId = new Map(dormantMoves.map((m) => [m.entry.id, m]));
+            const placeholders = dormantMoves.map(() => '?').join(',');
+            // SAFETY: rows' shape matches the three columns named in the SELECT.
+            const rows = db.prepare(`SELECT id, dag_parent_id, tenant_id FROM memories WHERE id IN (${placeholders}) AND ${AUTO_DELETABLE_SQL}`).all(...byId.keys());
+            for (const row of rows) {
+                movable.push(byId.get(row.id));
+                if (row.dag_parent_id) {
+                    dirtyParents.add(row.dag_parent_id);
+                    tenantById.set(row.dag_parent_id, row.tenant_id ?? 'default');
+                }
+            }
+        }
+        for (const move of movable) {
+            insertDormantRow(db, move);
+        }
+        const removedIds = [...deletableIds, ...movable.map((m) => m.entry.id)];
+        for (const id of removedIds) {
             db.prepare('DELETE FROM memories WHERE id = ?').run(id);
             deleteFtsRow(db, id);
         }
@@ -1670,15 +1780,14 @@ export function batchWriteAndDelete(hippoRoot, toWrite, toDeleteIds) {
         // Sync mirrors once after all DB writes. Entries skipped above were
         // never inserted — writing their markdown mirror would resurrect the
         // exact content the skip just kept out of the DB.
-        for (const entry of stampedWrites) {
-            if (skippedWriteIds.has(entry.id))
-                continue;
-            writeMarkdownMirror(hippoRoot, entry);
-        }
-        for (const id of toDeleteIds) {
-            removeEntryMirrors(hippoRoot, id);
-        }
+        mirrorBestEffort('markdown mirrors', () => {
+            for (const entry of written)
+                writeMarkdownMirror(hippoRoot, entry);
+        });
+        for (const id of removedIds)
+            purgeMirrorBestEffort(hippoRoot, id, false, 'batchWriteAndDelete');
         writeIndexMirror(hippoRoot, buildIndexFromDb(db));
+        return removedIds;
     }
     catch (error) {
         try {
@@ -1702,17 +1811,21 @@ export function loadAllEntries(hippoRoot, tenantId) {
     initStore(hippoRoot);
     const db = openHippoDb(hippoRoot);
     try {
-        // SAFETY: both branches select exactly MEMORY_SELECT_COLUMNS, matching
-        // MemoryRow's field set.
-        const rows = tenantId !== undefined
-            ? db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE tenant_id = ? ORDER BY created ASC, id ASC`).all(tenantId)
-            : db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories ORDER BY created ASC, id ASC`).all();
-        return rows.map(rowToEntry);
+        return selectAllEntries(db, tenantId);
     }
     finally {
         closeHippoDb(db);
     }
 }
+/** Every memory row on an open connection, so a caller can read inside its own transaction. */
+export function selectAllEntries(db, tenantId) {
+    // SAFETY: both branches select exactly MEMORY_SELECT_COLUMNS, matching
+    // MemoryRow's field set.
+    const rows = tenantId !== undefined
+        ? db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE tenant_id = ? ORDER BY created ASC, id ASC`).all(tenantId)
+        : db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories ORDER BY created ASC, id ASC`).all();
+    return rows.map(rowToEntry);
+}
 // The pins plus the `recentNeeded` newest rows that pass `admit`, for ambient
 // injection. One connection: opening one costs ~5.8ms on a warm 1896-row store,
 // so a second handle loses more than the narrower scan saves.
@@ -1799,7 +1912,7 @@ export function loadSearchEntries(hippoRoot, query, limit = DEFAULT_SEARCH_CANDI
  * mode (its `tenantId` option is optional); `loadSearchRows` already treats
  * undefined as "no tenant filter" for legacy callers.
  */
-export function loadRecallSearchEntries(hippoRoot, query, limit = DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId, requestedScope, explicitScopeMode = 'exact') {
+export function loadRecallSearchEntries(hippoRoot, query, limit = DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId, requestedScope, explicitScopeMode = 'exact', includeSuperseded = true) {
     initStore(hippoRoot);
     const db = openHippoDb(hippoRoot);
     try {
@@ -1812,7 +1925,7 @@ export function loadRecallSearchEntries(hippoRoot, query, limit = DEFAULT_SEARCH
                 ? { mode: 'default-deny-or-exact', value: requestedScope }
                 : { mode: 'exact', value: requestedScope }
             : { mode: 'default-deny' };
-        return loadSearchRows(db, query, limit, tenantId, scopeFilter).map(rowToEntry);
+        return loadSearchRows(db, query, limit, tenantId, scopeFilter, includeSuperseded).map(rowToEntry);
     }
     finally {
         closeHippoDb(db);
@@ -1903,9 +2016,7 @@ export function loadStats(hippoRoot) {
     initStore(hippoRoot);
     const db = openHippoDb(hippoRoot);
     try {
-        const stats = buildStatsFromDb(db);
-        writeStatsMirror(hippoRoot, stats);
-        return stats;
+        return buildStatsFromDb(db);
     }
     finally {
         closeHippoDb(db);
@@ -1923,6 +2034,20 @@ export function appendConsolidationRun(hippoRoot, run) {
         closeHippoDb(db);
     }
 }
+/** Rows a tenant created since the last sleep (runs are host-wide), looking back at most 24 hours. */
+export function countCreatedSinceLastSleep(hippoRoot, tenantId, now = new Date()) {
+    initStore(hippoRoot);
+    const db = openHippoDb(hippoRoot);
+    try {
+        const dayAgo = new Date(now.getTime() - 86_400_000).toISOString();
+        const row = db.prepare(`SELECT COUNT(*) AS n FROM memories WHERE tenant_id = ?
+         AND created > MAX(?, COALESCE((SELECT MAX(timestamp) FROM consolidation_runs), ''))`).get(tenantId, dayAgo);
+        return row.n;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 /**
  * Load the session decay context from the store.
  * Uses consolidation_runs timestamps to compute session intervals.
@@ -3492,6 +3617,7 @@ export function loadAllL2Summaries(hippoRoot) {
        WHERE dag_level = 2
          AND dag_parent_id IS NULL
          AND kind != 'archived'
+         AND superseded_by IS NULL
        ORDER BY created ASC, id ASC
     `).all();
         return rows.map(rowToEntry);
@@ -3548,6 +3674,7 @@ export function loadChildrenOfSummary(hippoRoot, summaryId, tenantId) {
        WHERE dag_parent_id = ?
          AND tenant_id = ?
          AND kind != 'archived'
+         AND superseded_by IS NULL
        ORDER BY created ASC
     `).all(summaryId, tenantId);
         return rows.map(rowToEntry);

package/dist/token-ledger.d.ts

@@ -0,0 +1,119 @@
+import type { DatabaseSyncLike } from './db.js';
+/**
+ * Where a block of memory text was sent.
+ * - `hook`: the per-prompt `UserPromptSubmit` hook (`hippo context --pinned-only`).
+ * - `context`, `recall`: the CLI commands.
+ * - `mcp_recall`, `mcp_context`: the MCP tools.
+ * - `http_recall`, `http_context`, `http_assemble`: the HTTP API.
+ */
+export type TokenSurface = 'hook' | 'context' | 'recall' | 'mcp_recall' | 'mcp_context' | 'http_recall' | 'http_context' | 'http_assemble';
+/** All surfaces, in report order. */
+export declare const TOKEN_SURFACES: readonly TokenSurface[];
+/**
+ * What happened to a block.
+ * - `inject`: sent to the agent.
+ * - `skip`: identical to the session's last injected block, so not sent again.
+ * - `reset`: the host compacted its context, so the next block must be sent.
+ */
+export type TokenEvent = 'inject' | 'skip' | 'reset';
+/** Rows older than this are pruned on write. */
+export declare const TOKEN_LEDGER_RETENTION_DAYS = 90;
+/**
+ * Rough token estimate: characters / 4. The single estimate behind every
+ * token budget and ledger count in hippo.
+ */
+export declare function estimateTokens(text: string): number;
+/** Stable 16-hex-char hash of a rendered block, for change detection. */
+export declare function blockHash(text: string): string;
+/** One ledger write. */
+export interface TokenUse {
+    tenantId: string;
+    /** Host session id when known (hook payload, `HIPPO_SESSION_ID`); null otherwise. */
+    sessionId?: string | null;
+    surface: TokenSurface;
+    event: TokenEvent;
+    /** Memories (and continuity blocks) in the text. */
+    items: number;
+    /** Estimated tokens of the text; for a `skip`, the tokens not sent. */
+    tokens: number;
+    /** {@link blockHash} of the text, when the caller wants change detection. */
+    hash?: string | null;
+    /** Override the timestamp (tests). ISO string. */
+    now?: string;
+}
+/**
+ * Append one ledger row and prune rows past {@link TOKEN_LEDGER_RETENTION_DAYS}.
+ */
+export declare function recordTokenUse(db: DatabaseSyncLike, use: TokenUse): void;
+/** What a session last sent on a surface, for {@link lastSentState}. */
+export interface LastSent {
+    /** {@link blockHash} of the last injected block. */
+    hash: string;
+    /** Consecutive `skip` rows since that injection. */
+    skipsSince: number;
+}
+/**
+ * The last block this session injected on `surface`, or null when the
+ * session has injected nothing, a `reset` came after it, or there is no
+ * session id (without one, the caller always injects).
+ */
+export declare function lastSentState(db: DatabaseSyncLike, tenantId: string, sessionId: string | null | undefined, surface: TokenSurface): LastSent | null;
+/**
+ * Whether a block identical to the session's last injection should be
+ * skipped. `refreshTurns` resends an unchanged block after that many
+ * consecutive skips, so a long session still sees its pinned rules near the
+ * latest turn; 0 never resends an unchanged block.
+ */
+export declare function shouldSkipUnchanged(last: LastSent | null, hash: string, refreshTurns: number): boolean;
+/** Per-surface totals for {@link summarizeTokenUse}. */
+export interface TokenSurfaceSummary {
+    surface: TokenSurface;
+    /** Blocks sent. */
+    injected: number;
+    /** Tokens sent. */
+    tokens: number;
+    /** Blocks not sent because they were unchanged. */
+    skipped: number;
+    /** Tokens those skipped blocks would have cost. */
+    tokensAvoided: number;
+    /** Distinct session ids seen (rows without one are not counted). */
+    sessions: number;
+}
+/** Ledger totals over a window. */
+export interface TokenSummary {
+    /** ISO start of the window (inclusive). */
+    since: string;
+    surfaces: TokenSurfaceSummary[];
+    totalTokens: number;
+    totalTokensAvoided: number;
+    /** Mean tokens sent per session, over rows that carry a session id. */
+    meanTokensPerSession: number;
+}
+/**
+ * Sum the ledger for one tenant since `sinceIso`. Surfaces with no rows are
+ * omitted.
+ */
+export declare function summarizeTokenUse(db: DatabaseSyncLike, tenantId: string, sinceIso: string): TokenSummary;
+/**
+ * The `session_id` of a Claude Code hook payload on stdin, or null when the
+ * text is empty, malformed, has no non-empty session id, or (with
+ * `requiredSource`) a different `source`.
+ */
+export declare function hookPayloadSessionId(stdinText: string | undefined, requiredSource?: string | null): string | null;
+/** Tokens hippo sent and skipped in one session, for {@link tokensBySession}. */
+export interface SessionTokens {
+    sessionId: string;
+    /** Tokens of memory text sent to the agent. */
+    sent: number;
+    /** Tokens of unchanged blocks not sent. */
+    skipped: number;
+    /** Blocks sent. */
+    injections: number;
+}
+/**
+ * Ledger totals per session id since `sinceIso`, across every surface.
+ * Claude Code hook rows carry the host's session id, which is also the
+ * transcript file name, so these join to the host's own usage records.
+ */
+export declare function tokensBySession(db: DatabaseSyncLike, tenantId: string, sinceIso: string): SessionTokens[];
+//# sourceMappingURL=token-ledger.d.ts.map