hippo-memory 1.44.0 → 1.46.0

package/dist/consolidate.js

@@ -7,12 +7,14 @@
  * 3. Stats tracking
  */
 import { evalNow, isRecallBoostAblated } from './ablation.js';
-import { Layer, calculateStrength, createMemory } from './memory.js';
+import { Layer, calculateStrength, canAutoDelete, createMemory } from './memory.js';
 import { loadAllEntries, batchWriteAndDelete, appendConsolidationRun, replaceDetectedConflicts, loadSessionDecayContext, incrementSleepCount, findPromotableSessions, traceExistsForSession, listSessionEvents, } from './store.js';
 import { textOverlap, markRetrieved } from './search.js';
 import { compareEntryIdentity } from './compare.js';
 import { openHippoDb, closeHippoDb } from './db.js';
 import { rejectionDigest, findRejectedValue } from './rejection.js';
+import { countExpiredDormant, purgeExpiredDormant } from './dormant.js';
+import { detectSecret } from './secret-detect.js';
 import { loadPhysicsState, savePhysicsState, refreshParticleProperties } from './physics-state.js';
 import { simulate } from './physics.js';
 import { loadConfig } from './config.js';
@@ -22,6 +24,7 @@ import { resolveTenantId } from './tenant.js';
 import { rescueSet, rankNonPinnedByTenant, validateWeights } from './memory-value.js';
 import { MEMORY_VALUE_WEIGHTS, SOURCE_ARTIFACT_SHA256 } from './memory-value-weights.js';
 import { appendAuditEvent } from './audit.js';
+import { migrateDefaultHalfLife } from './half-life-migration.js';
 const DECAY_THRESHOLD = 0.05;
 const MERGE_OVERLAP_THRESHOLD = 0.35; // Jaccard similarity for "related"
 const MERGE_MIN_CLUSTER = 2; // minimum cluster size to merge
@@ -59,6 +62,37 @@ const REPLAY_COUNT_DEFAULT = 5;
 function isJsonString(value) {
     return typeof value === 'string';
 }
+/** Tables whose rows keep a first-class object's backing memory in `memory_id` (ON DELETE SET NULL). */
+const MEMORY_BACKED_TABLES = ['predictions', 'decisions', 'processes', 'policies', 'skills', 'project_briefs', 'customer_notes'];
+/**
+ * Ids of memories that back a first-class object (a decision, prediction,
+ * process, policy, skill, project brief or customer note). Sleep never
+ * retires these: deleting or moving one to dormant storage fires the
+ * object's ON DELETE SET NULL and a restore cannot repair the link. Their
+ * lifecycle belongs to the object. A table missing from an older schema is
+ * skipped.
+ */
+function memoriesBackingObjects(hippoRoot) {
+    const ids = new Set();
+    const db = openHippoDb(hippoRoot);
+    try {
+        for (const table of MEMORY_BACKED_TABLES) {
+            try {
+                // SAFETY: SELECT of one nullable TEXT column, filtered to non-null.
+                const rows = db.prepare(`SELECT memory_id FROM ${table} WHERE memory_id IS NOT NULL`).all();
+                for (const r of rows)
+                    ids.add(r.memory_id);
+            }
+            catch {
+                // Table not present in this schema version.
+            }
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    return ids;
+}
 /**
  * Run a full consolidation pass.
  */
@@ -68,6 +102,8 @@ export async function consolidate(hippoRoot, options = {}) {
     const result = {
         decayed: 0,
         removed: 0,
+        dormant: 0,
+        dormantExpired: 0,
         merged: 0,
         semanticCreated: 0,
         replayed: 0,
@@ -86,11 +122,24 @@ export async function consolidate(hippoRoot, options = {}) {
         details: [],
         physicsSimulated: 0,
     };
+    // A changed default half-life moves memories still on the old base first,
+    // so this pass decays them at the new one (src/half-life-migration.ts).
+    const halfLife = migrateDefaultHalfLife(hippoRoot, loadConfig(hippoRoot).defaultHalfLifeDays, { dryRun });
+    if (halfLife.rescaled > 0) {
+        result.details.push(`  ⏳ ${dryRun ? 'would move' : 'moved'} ${halfLife.rescaled} memories from the ${halfLife.from}-day to the ${halfLife.to}-day half-life`);
+    }
     // L9: host-wide by design. Consolidation runs across all tenants in one
     // pass — per-tenant filtering would create N consolidation runs per host
     // with no cross-tenant dedup. The api.sleep audit row tags this with the
     // admin synthetic actor; see api.ts:2050 for the rationale.
     const all = loadAllEntries(hippoRoot);
+    if (dryRun)
+        for (const e of all)
+            e.half_life_days = halfLife.halfLives.get(e.id) ?? e.half_life_days;
+    const backingObjects = memoriesBackingObjects(hippoRoot);
+    // Retirable: auto-deletable (never pinned, never raw) and not backing a first-class object.
+    const retirable = (entry) => canAutoDelete(entry) && !backingObjects.has(entry.id);
+    const snapshot = new Map(structuredClone(all).map((e) => [e.id, e]));
     // Load decay options from config + session context
     const config = loadConfig(hippoRoot);
     const sessionCtx = loadSessionDecayContext(hippoRoot);
@@ -102,6 +151,28 @@ export async function consolidate(hippoRoot, options = {}) {
     // Collect all writes/deletes and batch them at the end
     const pendingWrites = [];
     const pendingDeletes = [];
+    const pendingDormant = [];
+    // A faded, unpinned, unrescued memory leaves active memory one of three
+    // ways. A raw receipt is append-only: trg_memories_raw_append_only aborts
+    // a DELETE, and with it this whole cycle's batch and every later sleep,
+    // so it stays where it is (stored strength refreshed) but sits out the
+    // rest of this cycle the way a deleted row would. Anything else goes
+    // dormant when config.dormant is on, and is deleted otherwise.
+    // Only called for rows `retirable` allows (never pinned, never raw, never backing a first-class object).
+    const retireFaded = (entry, strength) => {
+        const why = `(strength ${strength.toFixed(4)} < ${DECAY_THRESHOLD})`;
+        // A faded secret is deleted, never kept dormant: keeping it would hold a
+        // credential on disk that the user reasonably expects forgetting removed.
+        if (config.dormant.enabled && !detectSecret(entry).flagged) {
+            result.dormant++;
+            result.details.push(`  💤 dormant ${entry.id} ${why}`);
+            pendingDormant.push({ entry: { ...entry, strength }, strength, reason: 'decay', dormantAt: now.toISOString() });
+            return;
+        }
+        result.removed++;
+        result.details.push(`  🗑  removed ${entry.id} ${why}`);
+        pendingDeletes.push(entry.id);
+    };
     // -------------------------------------------------------------------------
     // 1. Decay pass
     // -------------------------------------------------------------------------
@@ -131,12 +202,12 @@ export async function consolidate(hippoRoot, options = {}) {
         for (const entry of all) {
             const strength = calculateStrength(entry, now, decayOpts);
             strengthById.set(entry.id, strength);
-            if (!entry.pinned && strength < DECAY_THRESHOLD) {
+            if (retirable(entry) && strength < DECAY_THRESHOLD) {
                 condemned.push(entry);
             }
         }
         // --- Phase 2a: rescue decision (pure compute) ---
-        // Runs under --dry-run too (only pendingDeletes/the audit write in
+        // Runs under --dry-run too (only the pendingDeletes flush and the audit write in
         // "4. Log run" below stay !dryRun-gated), so the preview matches what a
         // real run would decide.
         const condemnedIds = new Set(condemned.map((e) => e.id));
@@ -173,7 +244,7 @@ export async function consolidate(hippoRoot, options = {}) {
         // preserves flag-off's ordering semantics exactly.)
         for (const entry of all) {
             const strength = strengthById.get(entry.id);
-            if (!entry.pinned && strength < DECAY_THRESHOLD) {
+            if (retirable(entry) && strength < DECAY_THRESHOLD) {
                 if (rescuedIds.has(entry.id)) {
                     // Rescued (D1): standard survivor stored-strength refresh (P2-1).
                     // Confidence is left alone here: it is an epistemic tier, not a
@@ -192,11 +263,7 @@ export async function consolidate(hippoRoot, options = {}) {
                     result.details.push(`  🛟 ${entry.id} (strength ${strength.toFixed(4)} < ${DECAY_THRESHOLD})${rankNote}`);
                 }
                 else {
-                    result.removed++;
-                    result.details.push(`  🗑  removed ${entry.id} (strength ${strength.toFixed(4)} < ${DECAY_THRESHOLD})`);
-                    if (!dryRun) {
-                        pendingDeletes.push(entry.id);
-                    }
+                    retireFaded(entry, strength);
                 }
             }
             else {
@@ -212,12 +279,8 @@ export async function consolidate(hippoRoot, options = {}) {
     else {
         for (const entry of all) {
             const strength = calculateStrength(entry, now, decayOpts);
-            if (!entry.pinned && strength < DECAY_THRESHOLD) {
-                result.removed++;
-                result.details.push(`  🗑  removed ${entry.id} (strength ${strength.toFixed(4)} < ${DECAY_THRESHOLD})`);
-                if (!dryRun) {
-                    pendingDeletes.push(entry.id);
-                }
+            if (retirable(entry) && strength < DECAY_THRESHOLD) {
+                retireFaded(entry, strength);
             }
             else {
                 // Only strength is a cached computation; confidence stays as stored.
@@ -423,26 +486,34 @@ export async function consolidate(hippoRoot, options = {}) {
         // 1.6. Batch extraction — extract facts from episodic memories missing them
         // -------------------------------------------------------------------------
         const extractedFromIds = new Set(survivors.filter((e) => e.extracted_from).map((e) => e.extracted_from));
-        const extractionCandidates = survivors.filter((e) => e.layer === Layer.Episodic && !extractedFromIds.has(e.id));
+        const extractionCandidates = survivors.filter((e) => e.layer === Layer.Episodic && !e.superseded_by && !extractedFromIds.has(e.id));
         result.extractionCandidates = extractionCandidates.length;
-        const apiKey = process.env.ANTHROPIC_API_KEY ?? '';
+        // extraction.enabled=false is the opt-out for every LLM phase below, key or no key.
+        const apiKey = config.extraction.enabled !== false ? (process.env.ANTHROPIC_API_KEY ?? '') : '';
+        const llmErrorsSeen = new Set();
+        const llmError = (phase) => (msg) => {
+            const line = `  ⚠️ ${phase}: ${msg}`;
+            if (llmErrorsSeen.has(line))
+                return;
+            llmErrorsSeen.add(line);
+            result.details.push(line);
+            console.error(`consolidate ${phase}: ${msg}`);
+        };
+        const llmOpts = { apiKey, model: config.extraction.model, fetcher: options.fetcher };
         if (apiKey && extractionCandidates.length > 0 && !dryRun) {
             const { extractFacts, storeExtractedFacts } = await import('./extract.js');
             const batchLimit = 20;
             let extractedCount = 0;
             for (const candidate of extractionCandidates.slice(0, batchLimit)) {
                 try {
-                    const facts = await extractFacts(candidate.content, {
-                        apiKey,
-                        model: config.extraction.model,
-                    });
+                    const facts = await extractFacts(candidate.content, { ...llmOpts, onError: llmError('extraction') });
                     if (facts.length > 0) {
                         storeExtractedFacts(hippoRoot, candidate, facts);
                         extractedCount += facts.length;
                     }
                 }
-                catch {
-                    // Best-effort — continue with next candidate
+                catch (err) {
+                    llmError('extraction')(String(err));
                 }
             }
             result.extracted = extractedCount;
@@ -450,22 +521,19 @@ export async function consolidate(hippoRoot, options = {}) {
         // -------------------------------------------------------------------------
         // 1.7. DAG summarization — cluster extracted facts and generate summaries
         // -------------------------------------------------------------------------
-        const extractedFacts = survivors.filter((e) => e.tags.includes('extracted') && e.dag_level === 1);
+        const extractedFacts = survivors.filter((e) => e.tags.includes('extracted') && e.dag_level === 1 && !e.superseded_by);
         if (apiKey && extractedFacts.length >= 3 && !dryRun) {
             try {
                 const { buildDag } = await import('./dag.js');
-                const dagResult = await buildDag(hippoRoot, extractedFacts, {
-                    apiKey,
-                    model: config.extraction.model,
-                });
+                const dagResult = await buildDag(hippoRoot, extractedFacts, { ...llmOpts, onError: llmError('dag') });
                 result.dagCandidateClusters = dagResult.candidateClusters;
                 result.dagSummariesCreated = dagResult.summariesCreated;
                 if (dagResult.summariesCreated > 0) {
                     result.details.push(`  🌳 DAG: ${dagResult.summariesCreated} summaries created, ${dagResult.factsLinked} facts linked`);
                 }
             }
-            catch {
-                // Best-effort
+            catch (err) {
+                llmError('dag')(String(err));
             }
         }
         // -------------------------------------------------------------------------
@@ -485,11 +553,7 @@ export async function consolidate(hippoRoot, options = {}) {
                 const cap = Number.isFinite(rawCap) && rawCap > 0
                     ? Math.min(rawCap, 1000)
                     : 20;
-                const rebuildResult = await rebuildDirtySummaries(hippoRoot, {
-                    apiKey,
-                    model: config.extraction.model,
-                    cap,
-                });
+                const rebuildResult = await rebuildDirtySummaries(hippoRoot, { ...llmOpts, onError: llmError('dag rebuild'), cap });
                 result.summariesRebuilt = rebuildResult.rebuilt;
                 result.summariesRebuildFailed = rebuildResult.failed;
                 result.summariesZeroChildSkipped = rebuildResult.zeroChildSkipped;
@@ -510,8 +574,8 @@ export async function consolidate(hippoRoot, options = {}) {
                     result.details.push(`  🌳 DAG rebuild: ${parts.join(', ')}`);
                 }
             }
-            catch {
-                // Best-effort — same posture as buildDag block above.
+            catch (err) {
+                llmError('dag rebuild')(String(err));
             }
         }
         // -------------------------------------------------------------------------
@@ -529,18 +593,15 @@ export async function consolidate(hippoRoot, options = {}) {
                 const { loadAllL2Summaries } = await import('./store.js');
                 const l2Summaries = loadAllL2Summaries(hippoRoot);
                 if (l2Summaries.length >= 2) {
-                    const profileResult = await buildEntityProfiles(hippoRoot, l2Summaries, {
-                        apiKey,
-                        model: config.extraction.model,
-                    });
+                    const profileResult = await buildEntityProfiles(hippoRoot, l2Summaries, { ...llmOpts, onError: llmError('dag profiles') });
                     result.entityProfilesCreated = profileResult.profilesCreated;
                     if (profileResult.profilesCreated > 0) {
                         result.details.push(`  🌲 DAG L3: ${profileResult.profilesCreated} entity profiles, ${profileResult.l2sLinked} L2s linked`);
                     }
                 }
             }
-            catch {
-                // Best-effort.
+            catch (err) {
+                llmError('dag profiles')(String(err));
             }
         }
         // -------------------------------------------------------------------------
@@ -599,7 +660,7 @@ export async function consolidate(hippoRoot, options = {}) {
         // -------------------------------------------------------------------------
         // 3. Merge pass  - episodic entries only
         // -------------------------------------------------------------------------
-        const mergeCandidates = survivors.filter((e) => e.layer === Layer.Episodic && !e.tags.includes('extracted'));
+        const mergeCandidates = survivors.filter((e) => e.layer === Layer.Episodic && !e.superseded_by && !e.tags.includes('extracted'));
         const used = new Set();
         // T1 fix (2026-08-15 hardening pass): partition by tenantId BEFORE the
         // overlap loop so a cluster can never span tenants. Previously textOverlap
@@ -735,9 +796,35 @@ export async function consolidate(hippoRoot, options = {}) {
     if (mergesSkippedRejected > 0) {
         console.error(`consolidate: skipped ${mergesSkippedRejected} merge(s) whose content matches a rejected value`);
     }
-    // Flush all writes/deletes in a single transaction
+    result.removedIds = pendingDeletes;
+    // One transaction; the snapshot keeps what the DAG passes and other writers changed while sleep ran.
+    // Dormant moves ride in the same transaction (src/dormant.ts).
     if (!dryRun) {
-        batchWriteAndDelete(hippoRoot, pendingWrites, pendingDeletes);
+        const left = new Set(batchWriteAndDelete(hippoRoot, pendingWrites, pendingDeletes, { snapshot, dormant: pendingDormant }));
+        for (const id of [...pendingDeletes, ...pendingDormant.map((m) => m.entry.id)]) {
+            if (!left.has(id))
+                result.details.push(`  ↩  ${id} not removed: pinned or already gone before sleep saved`);
+        }
+        result.removedIds = pendingDeletes.filter((id) => left.has(id));
+        result.removed = result.removedIds.length;
+        result.dormant = pendingDormant.filter((m) => left.has(m.entry.id)).length;
+    }
+    // Dormant retention: a dormant memory nobody restored within
+    // dormant.retentionDays is deleted for good (0 keeps them forever). Runs
+    // even when dormant.enabled is off, so turning it off still ages out what
+    // earlier sleeps kept.
+    if (config.dormant.retentionDays > 0) {
+        const cutoff = new Date(now.getTime() - config.dormant.retentionDays * 24 * 60 * 60 * 1000).toISOString();
+        const db = openHippoDb(hippoRoot);
+        try {
+            result.dormantExpired = dryRun ? countExpiredDormant(db, cutoff) : purgeExpiredDormant(db, cutoff);
+        }
+        finally {
+            closeHippoDb(db);
+        }
+        if (result.dormantExpired > 0) {
+            result.details.push(`  ⌛ ${dryRun ? 'would expire' : 'expired'} ${result.dormantExpired} dormant memor${result.dormantExpired === 1 ? 'y' : 'ies'} older than ${config.dormant.retentionDays} days`);
+        }
     }
     // -------------------------------------------------------------------------
     // 4. Log run

package/dist/dag.d.ts

@@ -9,6 +9,7 @@ export interface DagSummaryOptions {
     apiKey: string;
     model?: string;
     fetcher?: typeof fetch;
+    onError?: (msg: string) => void;
 }
 export declare function generateDagSummary(label: string, factContents: string[], opts: DagSummaryOptions): Promise<string | null>;
 export interface DagBuildResult {

package/dist/dag.js

@@ -1,6 +1,7 @@
 import { createMemory, Layer } from './memory.js';
 import { writeEntry, loadAllDirtySummaries, loadChildrenOfSummary, applyRebuildResult, clearSummaryDirtyAfterBuild, } from './store.js';
 import { RejectedValueError } from './rejection.js';
+import { redactSecrets } from './secret-detect.js';
 export function clusterFacts(facts) {
     if (facts.length === 0)
         return [];
@@ -42,9 +43,9 @@ Write a single concise paragraph (2-4 sentences) that captures all the key infor
 export async function generateDagSummary(label, factContents, opts) {
     const model = opts.model ?? 'claude-sonnet-4-6';
     const fetchFn = opts.fetcher ?? fetch;
-    const factsBlock = factContents.map((f, i) => `${i + 1}. ${f}`).join('\n');
+    const factsBlock = factContents.map((f, i) => `${i + 1}. ${redactSecrets(f)}`).join('\n');
     const prompt = DAG_SUMMARY_PROMPT
-        .replace('{label}', label)
+        .replace('{label}', redactSecrets(label))
         .replace('{facts}', factsBlock);
     let res;
     try {
@@ -62,17 +63,21 @@ export async function generateDagSummary(label, factContents, opts) {
             }),
         });
     }
-    catch {
+    catch (err) {
+        opts.onError?.(`request failed: ${err instanceof Error ? err.message : String(err)}`);
         return null;
     }
-    if (!res.ok)
+    if (!res.ok) {
+        opts.onError?.(`HTTP ${res.status}`);
         return null;
+    }
     try {
         const data = await res.json();
         const text = data.content?.[0]?.text?.trim() ?? '';
         return text.length >= 20 ? text : null;
     }
-    catch {
+    catch (err) {
+        opts.onError?.(`unparseable response: ${err instanceof Error ? err.message : String(err)}`);
         return null;
     }
 }

package/dist/dashboard.js

@@ -14,6 +14,7 @@ import { listPeers } from './shared.js';
 import { loadEmbeddingIndex } from './embeddings.js';
 import { resolveTenantId } from './tenant.js';
 import { loadCardDetail } from './card-detail.js';
+import { isCrossSite, LOOPBACK_HOST_HEADER } from './server.js';
 function buildDashboardData(hippoRoot) {
     // A5: scope dashboard to active tenant. Without this, the UI surfaces every
     // tenant's memories on a multi-tenant deployment.
@@ -122,8 +123,6 @@ const MIME_TYPES = {
     '.ico': 'image/x-icon',
     '.woff2': 'font/woff2',
 };
-// Binds 127.0.0.1 only; refusing other Hosts closes the DNS-rebinding route.
-const LOOPBACK_HOST = /^(localhost|127\.0\.0\.1)(:\d+)?$/i;
 function isStaticFileExtension(ext) {
     return Object.hasOwn(MIME_TYPES, ext);
 }
@@ -156,7 +155,7 @@ export function serveDashboard(hippoRoot, port = 3333) {
     const hasDistUi = fs.existsSync(path.join(distUiDir, 'index.html'));
     const handleRequest = (req, res) => {
         const host = req.headers.host;
-        if (host !== undefined && !LOOPBACK_HOST.test(host)) {
+        if (host !== undefined && !LOOPBACK_HOST_HEADER.test(host)) {
             res.writeHead(403, { 'Content-Type': 'text/plain' });
             res.end('Forbidden');
             return;
@@ -168,6 +167,11 @@ export function serveDashboard(hippoRoot, port = 3333) {
             // POST /api/star/:id - toggle starred on a memory
             const starMatch = pathname.match(/^\/api\/star\/([A-Za-z0-9_\-]+)$/);
             if (starMatch && req.method === 'POST') {
+                if (isCrossSite(req)) {
+                    res.writeHead(403, { 'Content-Type': 'text/plain' });
+                    res.end('Forbidden');
+                    return;
+                }
                 const id = starMatch[1];
                 const entry = readEntry(hippoRoot, id, resolveTenantId({}));
                 if (!entry)

package/dist/db.js

@@ -11,7 +11,7 @@ const require = createRequire(import.meta.url);
 // runtime (Node's built-in synchronous SQLite module); there are no bundled
 // types for it here, so this require + cast is the module's documented boundary.
 const { DatabaseSync } = require('node:sqlite');
-const CURRENT_SCHEMA_VERSION = 43;
+const CURRENT_SCHEMA_VERSION = 45;
 const MIGRATIONS = [
     {
         version: 1,
@@ -2367,6 +2367,62 @@ const MIGRATIONS = [
       `);
         },
     },
+    {
+        version: 44,
+        up: (db) => {
+            // Dormant memories (src/dormant.ts): with `dormant.enabled`, the sleep
+            // decay pass moves a faded memory here instead of deleting it. The row
+            // leaves `memories` in the same transaction, so recall, context and
+            // every sleep pass stop seeing it; entry_json is the full MemoryEntry
+            // snapshot `hippo dormant restore` writes back. No FK to memories (the
+            // memories row is gone by design). Additive only, v41 precedent: no
+            // min_compatible_binary bump. An older binary ignores the table and
+            // keeps deleting faded memories as it always did.
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS dormant_memories (
+          tenant_id  TEXT NOT NULL DEFAULT 'default',
+          id         TEXT NOT NULL,
+          content    TEXT NOT NULL,
+          entry_json TEXT NOT NULL,
+          reason     TEXT NOT NULL,
+          strength   REAL NOT NULL,
+          dormant_at TEXT NOT NULL,
+          PRIMARY KEY (tenant_id, id)
+        ) WITHOUT ROWID;
+        CREATE INDEX IF NOT EXISTS idx_dormant_memories_tenant_time
+          ON dormant_memories(tenant_id, dormant_at DESC);
+      `);
+        },
+    },
+    {
+        version: 45,
+        up: (db) => {
+            // Token ledger (src/token-ledger.ts, ROADMAP TE0): one row per block of
+            // memory text hippo hands an agent (hook, CLI, MCP, HTTP). `event` is
+            // 'inject' (sent), 'skip' (unchanged since the session's last inject,
+            // not sent) or 'reset' (compaction dropped earlier injections, so the
+            // next one must be sent). block_hash lets the per-prompt hook skip an
+            // unchanged block. Rows older than the retention window are pruned on
+            // write. Additive only: no min_compatible_binary bump.
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS token_ledger (
+          id         INTEGER PRIMARY KEY AUTOINCREMENT,
+          ts         TEXT NOT NULL,
+          tenant_id  TEXT NOT NULL DEFAULT 'default',
+          session_id TEXT,
+          surface    TEXT NOT NULL,
+          event      TEXT NOT NULL,
+          items      INTEGER NOT NULL DEFAULT 0,
+          tokens     INTEGER NOT NULL DEFAULT 0,
+          block_hash TEXT
+        );
+        CREATE INDEX IF NOT EXISTS idx_token_ledger_session
+          ON token_ledger(tenant_id, session_id, surface, id DESC);
+        CREATE INDEX IF NOT EXISTS idx_token_ledger_ts
+          ON token_ledger(ts);
+      `);
+        },
+    },
 ];
 function tableHasColumn(db, tableName, columnName) {
     if (!/^[a-z_]+$/i.test(tableName))
@@ -2389,16 +2445,12 @@ export function getHippoDbPath(hippoRoot) {
 export function getCurrentSchemaVersion() {
     return CURRENT_SCHEMA_VERSION;
 }
-function readMinCompatibleBinary(db) {
-    // Tolerate the meta table not yet existing on a fresh DB.
-    try {
-        // SAFETY: row's shape matches the single `value` column named in the
-        // SELECT above.
-        const row = db.prepare(`SELECT value FROM meta WHERE key = 'min_compatible_binary'`).get();
-        return row?.value ?? null;
-    }
-    catch {
-        return null;
+/** Refuse a store stamped for a newer binary. Fails closed: runMigrations creates meta first, so a failed read is a real error. */
+function assertBinaryCompatible(db) {
+    const minRequired = getMeta(db, 'min_compatible_binary');
+    if (minRequired && compareSemver(minRequired, PACKAGE_VERSION) > 0) {
+        throw new Error(`hippo-memory: this database requires hippo-memory >= ${minRequired}, but the running binary is ${PACKAGE_VERSION}. ` +
+            `Upgrade hippo-memory to open it; an older binary does not know this schema and could expose private rows or damage the store.`);
     }
 }
 function isSqliteBusy(error) {
@@ -2456,17 +2508,8 @@ export function openHippoDb(hippoRoot) {
 }
 function runMigrations(db, hippoRoot) {
     ensureMetaTable(db);
-    // v1.3.1 rollback-safety guard. Schema v24 stamped meta.min_compatible_binary;
-    // older binaries that lack the generic *:private:* default-deny filter would
-    // leak github:private:* rows on no-scope recall. Refuse to open a DB stamped
-    // with a min newer than this binary's version. Read BEFORE migrations so a
-    // stale v1.2.0 binary cannot apply unknown future migrations either.
-    const minRequired = readMinCompatibleBinary(db);
-    if (minRequired && compareSemver(minRequired, PACKAGE_VERSION) > 0) {
-        throw new Error(`hippo-memory: this database requires hippo-memory >= ${minRequired}, but the running binary is ${PACKAGE_VERSION}. ` +
-            `Upgrade hippo-memory to open this database. Running an older binary against this DB would leak private rows that the ` +
-            `older filter does not recognize.`);
-    }
+    // Before anything writes, so a stale binary never repairs or migrates a store it does not understand.
+    assertBinaryCompatible(db);
     let currentVersion = getSchemaVersion(db);
     if (currentVersion > 0)
         ensureContinuityTables(db);
@@ -2475,6 +2518,8 @@ function runMigrations(db, hippoRoot) {
             continue;
         execWithBusyRetry(db, 'BEGIN IMMEDIATE');
         try {
+            // A newer binary may have migrated and raised the minimum while we waited for the lock.
+            assertBinaryCompatible(db);
             // Re-read under the write lock: another process may have applied this
             // migration while we waited, and re-running one is not idempotent.
             const applied = getSchemaVersion(db);
@@ -2672,8 +2717,8 @@ function ensureOptionalFts(db) {
         backfillFtsIndex(db);
         available = true;
     }
-    catch {
-        available = false;
+    catch (err) {
+        console.error(`hippo: full-text index unavailable (${err instanceof Error ? err.message : String(err)}); search falls back to slower LIKE matching`);
     }
     // Read-first: only write when the flag actually changed, so a healthy
     // store's open doesn't take a write lock for a same-value upsert.

package/dist/dedupe.d.ts

@@ -70,5 +70,6 @@ export declare function strengthBucket(strength: number | null | undefined): num
 export declare function deduplicateStore(hippoRoot: string, options?: {
     threshold?: number;
     dryRun?: boolean;
+    actor?: string;
 }): DedupResult;
 //# sourceMappingURL=dedupe.d.ts.map

package/dist/dedupe.js

@@ -23,6 +23,7 @@
 import { textOverlap } from './search.js';
 import { loadAllEntries, deleteEntry } from './store.js';
 import { compareEntryIdentity } from './compare.js';
+import { canAutoDelete } from './memory.js';
 /** Quantization step for strength-tie comparisons. The historical 0.01
  *  epsilon (see `strengthBucket` below) applied via rounding instead of a
  *  raw abs-diff threshold, so the tiebreak is transitive. */
@@ -111,7 +112,7 @@ export function deduplicateStore(hippoRoot, options = {}) {
             if (removed.has(tenantEntries[i].id))
                 continue;
             for (let j = i + 1; j < tenantEntries.length; j++) {
-                if (removed.has(tenantEntries[j].id))
+                if (removed.has(tenantEntries[j].id) || !canAutoDelete(tenantEntries[j]))
                     continue;
                 const similarity = textOverlap(tenantEntries[i].content, tenantEntries[j].content);
                 if (similarity <= threshold)
@@ -131,11 +132,7 @@ export function deduplicateStore(hippoRoot, options = {}) {
             }
         }
     }
-    if (!dryRun) {
-        for (const id of removed) {
-            deleteEntry(hippoRoot, id);
-        }
-    }
-    return { removed: removed.size, pairs };
+    const done = dryRun ? pairs : pairs.filter((p) => deleteEntry(hippoRoot, p.removed, { actor: options.actor, reason: `dedup: duplicate of ${p.kept}`, automatic: true }));
+    return { removed: done.length, pairs: done };
 }
 //# sourceMappingURL=dedupe.js.map

package/dist/doctor.d.ts

@@ -0,0 +1,34 @@
+/** Outcome of one check. `fail` makes `hippo doctor` exit 1. */
+export type DoctorStatus = 'pass' | 'warn' | 'fail' | 'info';
+/** One check in a {@link DoctorReport}. */
+export interface DoctorCheck {
+    id: string;
+    status: DoctorStatus;
+    detail: string;
+    /** Command or step that resolves a warn or fail. */
+    fix?: string;
+}
+/** Result of {@link runDoctor}. */
+export interface DoctorReport {
+    ok: boolean;
+    version: string;
+    /** The store the checks ran against, or null when none exists. */
+    store: string | null;
+    checks: DoctorCheck[];
+}
+/** Inputs for {@link runDoctor}; defaults come from the process. */
+export interface DoctorOpts {
+    cwd?: string;
+    /** Home directory used to find agent configuration (~/.claude). */
+    home?: string;
+    version: string;
+    nodeVersion?: string;
+    now?: Date;
+}
+/** Minimum Node.js version hippo supports (package.json engines). */
+export declare const MIN_NODE = "22.16.0";
+/** Run every check. Never throws for a broken install; broken parts become failed checks. */
+export declare function runDoctor(opts: DoctorOpts): DoctorReport;
+/** Human-readable rendering of a {@link DoctorReport}. */
+export declare function formatDoctor(report: DoctorReport): string;
+//# sourceMappingURL=doctor.d.ts.map