hippo-memory 1.45.0 → 1.46.0

package/dist/config.d.ts

@@ -62,6 +62,13 @@ export interface HippoConfig {
     pinnedInject: {
         enabled: boolean;
         budget: number;
+        /** Skip a block identical to the one already injected this session
+         *  (ROADMAP TE2). Default true. Needs a session id from the hook payload. */
+        skipUnchanged: boolean;
+        /** Resend an unchanged block after this many consecutive skips, so long
+         *  sessions still see pinned rules near the latest turn. Default 10; 0
+         *  never resends an unchanged block. */
+        refreshTurns: number;
     };
     /** Memory scope isolation (v39): when true (default), ambient context
      *  (`hippo context`, the UserPromptSubmit hook, /v1/context, MCP
@@ -96,6 +103,19 @@ export interface HippoConfig {
     memoryValue: {
         enabled: boolean;
     };
+    /** Dormant memories (src/dormant.ts): when enabled (the default), the
+     *  sleep decay pass moves a memory that faded below the threshold into the
+     *  dormant store instead of deleting it. A dormant memory leaves recall and
+     *  context like a deleted one, but `hippo dormant restore <id>` brings it
+     *  back and `hippo dormant forget <id>` deletes it for good. A faded memory
+     *  the secret detector flags is always deleted, never kept dormant.
+     *  `{"enabled": false}` restores the old delete-on-fade behaviour. */
+    dormant: {
+        enabled: boolean;
+        /** Days a dormant memory is kept before sleep deletes it for good.
+         *  Default 180. 0 keeps dormant memories forever. */
+        retentionDays: number;
+    };
 }
 export declare function loadConfig(hippoRoot: string): HippoConfig;
 export declare function saveConfig(hippoRoot: string, config: HippoConfig): void;

package/dist/config.js

@@ -45,6 +45,8 @@ const DEFAULT_CONFIG = {
     pinnedInject: {
         enabled: true,
         budget: 1500,
+        skipUnchanged: true,
+        refreshTurns: 10,
     },
     contextProjectIsolation: true,
     extraction: {
@@ -67,10 +69,17 @@ const DEFAULT_CONFIG = {
     memoryValue: {
         enabled: false,
     },
+    dormant: {
+        enabled: true,
+        retentionDays: 180,
+    },
 };
 function isMemoryValueConfig(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+function isDormantConfig(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 export function loadConfig(hippoRoot) {
     const configPath = path.join(hippoRoot, 'config.json');
     if (!fs.existsSync(configPath))
@@ -93,6 +102,28 @@ export function loadConfig(hippoRoot) {
                 `(got ${JSON.stringify(memoryValueRaw)}) - using defaults.`);
         }
         const memoryValueOverride = memoryValueRaw !== undefined && isMemoryValueConfig(memoryValueRaw) ? memoryValueRaw : {};
+        // Same rule as memoryValue above: a malformed value never silently
+        // changes what sleep does. Anything but a real object / boolean / number
+        // warns and falls back to the default, which keeps faded memories.
+        const dormantRaw = raw.dormant;
+        if (dormantRaw !== undefined && !isDormantConfig(dormantRaw)) {
+            console.error(`Warning: config.json's "dormant" must be an object like {"enabled": false} ` +
+                `(got ${JSON.stringify(dormantRaw)}) - using the default (faded memories kept dormant).`);
+        }
+        const dormantOverride = dormantRaw !== undefined && isDormantConfig(dormantRaw) ? dormantRaw : {};
+        // Only a real boolean counts: {"enabled": "false"} is a truthy string.
+        let dormantEnabled = dormantOverride.enabled ?? DEFAULT_CONFIG.dormant.enabled;
+        if (dormantEnabled !== true && dormantEnabled !== false) {
+            console.error(`Warning: config.json's "dormant.enabled" must be true or false ` +
+                `(got ${JSON.stringify(dormantEnabled)}) - using the default (faded memories kept dormant).`);
+            dormantEnabled = DEFAULT_CONFIG.dormant.enabled;
+        }
+        let dormantRetentionDays = dormantOverride.retentionDays ?? DEFAULT_CONFIG.dormant.retentionDays;
+        if (!Number.isFinite(dormantRetentionDays) || dormantRetentionDays < 0) {
+            console.error(`Warning: config.json's "dormant.retentionDays" must be a number of days, 0 or more ` +
+                `(got ${JSON.stringify(dormantRetentionDays)}) - using ${DEFAULT_CONFIG.dormant.retentionDays}.`);
+            dormantRetentionDays = DEFAULT_CONFIG.dormant.retentionDays;
+        }
         return {
             defaultHalfLifeDays: raw.defaultHalfLifeDays ?? DEFAULT_CONFIG.defaultHalfLifeDays,
             defaultBudget: raw.defaultBudget ?? DEFAULT_CONFIG.defaultBudget,
@@ -120,6 +151,10 @@ export function loadConfig(hippoRoot) {
                 ...DEFAULT_CONFIG.memoryValue,
                 ...memoryValueOverride,
             },
+            dormant: {
+                enabled: dormantEnabled,
+                retentionDays: dormantRetentionDays,
+            },
         };
     }
     catch (err) {

package/dist/consolidate.d.ts

@@ -9,6 +9,12 @@
 export interface ConsolidationResult {
     decayed: number;
     removed: number;
+    /** Faded memories moved to the dormant store instead of deleted (config
+     *  `dormant.enabled`; src/dormant.ts). Always 0 when that is off. */
+    dormant: number;
+    /** Dormant memories deleted for good this sleep because they outlived
+     *  `dormant.retentionDays` without a restore. */
+    dormantExpired: number;
     merged: number;
     semanticCreated: number;
     replayed: number;

package/dist/consolidate.js

@@ -13,6 +13,8 @@ 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,23 @@ 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);
@@ -103,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
     // -------------------------------------------------------------------------
@@ -132,7 +202,7 @@ export async function consolidate(hippoRoot, options = {}) {
         for (const entry of all) {
             const strength = calculateStrength(entry, now, decayOpts);
             strengthById.set(entry.id, strength);
-            if (canAutoDelete(entry) && strength < DECAY_THRESHOLD) {
+            if (retirable(entry) && strength < DECAY_THRESHOLD) {
                 condemned.push(entry);
             }
         }
@@ -174,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 (canAutoDelete(entry) && 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
@@ -193,9 +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})`);
-                    pendingDeletes.push(entry.id);
+                    retireFaded(entry, strength);
                 }
             }
             else {
@@ -211,10 +279,8 @@ export async function consolidate(hippoRoot, options = {}) {
     else {
         for (const entry of all) {
             const strength = calculateStrength(entry, now, decayOpts);
-            if (canAutoDelete(entry) && strength < DECAY_THRESHOLD) {
-                result.removed++;
-                result.details.push(`  🗑  removed ${entry.id} (strength ${strength.toFixed(4)} < ${DECAY_THRESHOLD})`);
-                pendingDeletes.push(entry.id);
+            if (retirable(entry) && strength < DECAY_THRESHOLD) {
+                retireFaded(entry, strength);
             }
             else {
                 // Only strength is a cached computation; confidence stays as stored.
@@ -732,14 +798,33 @@ export async function consolidate(hippoRoot, options = {}) {
     }
     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) {
-        const deleted = new Set(batchWriteAndDelete(hippoRoot, pendingWrites, pendingDeletes, { snapshot }));
-        for (const id of pendingDeletes) {
-            if (!deleted.has(id))
+        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) => deleted.has(id));
+        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/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))

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

package/dist/doctor.js

@@ -0,0 +1,174 @@
+/**
+ * `hippo doctor`: a health check people and agents can run after installing
+ * hippo, or when something seems off. Read-only: it never creates a store,
+ * installs a hook or migrates a database. Every non-passing check names the
+ * command that fixes it, so an agent can act on the `--json` output.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { findHippoStoreDir } from './project-identity.js';
+import { getGlobalRoot } from './shared.js';
+import { isInitialized, loadStats } from './store.js';
+import { openHippoDb, closeHippoDb, getSchemaVersion, getCurrentSchemaVersion } from './db.js';
+import { isEmbeddingAvailable } from './embeddings.js';
+/** Minimum Node.js version hippo supports (package.json engines). */
+export const MIN_NODE = '22.16.0';
+function versionAtLeast(actual, min) {
+    const a = actual.replace(/^v/, '').split('.').map(Number);
+    const b = min.split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        const x = a[i] ?? 0;
+        const y = b[i] ?? 0;
+        if (x !== y)
+            return x > y;
+    }
+    return true;
+}
+function readJson(file) {
+    try {
+        // SAFETY: JSON.parse returns a JSON value by definition.
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function countRows(db, table) {
+    try {
+        // SAFETY: COUNT(*) returns one row with one numeric column.
+        const row = db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get();
+        return Number(row?.n ?? 0);
+    }
+    catch {
+        return null;
+    }
+}
+/** Run every check. Never throws for a broken install; broken parts become failed checks. */
+export function runDoctor(opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    const home = opts.home ?? os.homedir();
+    const now = opts.now ?? new Date();
+    const checks = [];
+    const node = opts.nodeVersion ?? process.versions.node;
+    checks.push(versionAtLeast(node, MIN_NODE)
+        ? { id: 'node', status: 'pass', detail: `Node.js ${node}` }
+        : { id: 'node', status: 'fail', detail: `Node.js ${node} is older than ${MIN_NODE}`, fix: `Install Node.js ${MIN_NODE} or newer` });
+    const local = findHippoStoreDir(cwd);
+    const globalRoot = getGlobalRoot();
+    const hasGlobal = isInitialized(globalRoot);
+    let store = null;
+    if (local !== null) {
+        store = local;
+        checks.push({ id: 'store', status: 'pass', detail: `project store at ${local}${hasGlobal ? ` (global store at ${globalRoot} too)` : ''}` });
+    }
+    else if (hasGlobal) {
+        store = globalRoot;
+        checks.push({ id: 'store', status: 'warn', detail: `no project store here; using the global store at ${globalRoot}`, fix: 'hippo init   (in the project root)' });
+    }
+    else {
+        checks.push({ id: 'store', status: 'fail', detail: 'no hippo store found (project or global)', fix: 'hippo init   (in the project root), or hippo init --global' });
+    }
+    if (store !== null) {
+        let db = null;
+        try {
+            db = openHippoDb(store);
+            const have = getSchemaVersion(db);
+            const want = getCurrentSchemaVersion();
+            checks.push(have === want
+                ? { id: 'schema', status: 'pass', detail: `database schema v${have}` }
+                : have > want
+                    ? { id: 'schema', status: 'fail', detail: `database schema v${have} is newer than this hippo (v${want})`, fix: 'npm install -g hippo-memory@latest' }
+                    : { id: 'schema', status: 'info', detail: `database schema v${have}; hippo migrates it to v${want} on the next write` });
+            const memories = countRows(db, 'memories');
+            const dormant = countRows(db, 'dormant_memories');
+            const memoryCheck = { id: 'memories', status: 'info', detail: `${memories ?? '?'} memories${dormant !== null ? `, ${dormant} dormant` : ''}` };
+            if (memories === 0) {
+                memoryCheck.status = 'warn';
+                memoryCheck.fix = 'hippo learn --git   (seed lessons from git history)';
+            }
+            checks.push(memoryCheck);
+            const since = new Date(now.getTime() - 7 * 86_400_000).toISOString();
+            try {
+                // SAFETY: COUNT/SUM aggregate row.
+                const row = db.prepare(`SELECT COUNT(*) AS n, COALESCE(SUM(tokens), 0) AS t FROM token_ledger WHERE ts >= ? AND event = 'inject'`).get(since);
+                checks.push({ id: 'tokens', status: 'info', detail: `${Number(row?.n ?? 0)} memory blocks sent to agents in 7 days, about ${Number(row?.t ?? 0)} tokens (hippo tokens for detail)` });
+            }
+            catch {
+                checks.push({ id: 'tokens', status: 'info', detail: 'no token ledger yet (created on the next write)' });
+            }
+        }
+        catch (err) {
+            checks.push({ id: 'schema', status: 'fail', detail: `cannot open the database: ${err instanceof Error ? err.message : String(err)}`, fix: 'check file permissions on the .hippo folder' });
+        }
+        finally {
+            if (db !== null)
+                closeHippoDb(db);
+        }
+        try {
+            const runs = loadStats(store)['consolidation_runs'];
+            const last = Array.isArray(runs) && runs.length > 0 ? runs[runs.length - 1] : null;
+            // SAFETY: the constructor check above narrows `last` to a plain JSON object.
+            const ts = last !== null && last !== undefined && !Array.isArray(last) && last.constructor === Object ? last.timestamp : undefined;
+            const when = ts !== undefined && ts !== null ? Date.parse(String(ts)) : Number.NaN;
+            if (Number.isNaN(when)) {
+                checks.push({ id: 'sleep', status: 'warn', detail: 'hippo has never slept (consolidated) in this store', fix: 'hippo sleep   (the session-end hook runs it automatically)' });
+            }
+            else {
+                const days = Math.floor((now.getTime() - when) / 86_400_000);
+                checks.push(days > 7
+                    ? { id: 'sleep', status: 'warn', detail: `last sleep ${days} days ago`, fix: 'hippo sleep, and check the session-end hook is installed' }
+                    : { id: 'sleep', status: 'pass', detail: `last sleep ${days === 0 ? 'today' : `${days} day${days === 1 ? '' : 's'} ago`}` });
+            }
+        }
+        catch {
+            checks.push({ id: 'sleep', status: 'info', detail: 'sleep history unavailable' });
+        }
+    }
+    const claudeDir = path.join(home, '.claude');
+    if (fs.existsSync(claudeDir)) {
+        const settings = readJson(path.join(claudeDir, 'settings.json'));
+        const text = settings === null ? '' : JSON.stringify(settings);
+        const viaPlugin = /hippo-memory@/.test(text);
+        // Each hook and what it does, so a partial install says what is missing.
+        const hooks = [
+            ['hippo context --pinned-only', 'per-prompt memory'],
+            ['hippo session-end', 'session-end capture and sleep'],
+            ['hippo pre-compact', 'compaction snapshot and capture'],
+            ['hippo compact-resume', 'resume after compaction'],
+            ['hippo post-compact', 'the message after compaction'],
+            ['hippo capture-error', 'failed-tool capture'],
+        ];
+        const missing = hooks.filter(([marker]) => !text.includes(marker)).map(([, what]) => what);
+        if (viaPlugin) {
+            checks.push({ id: 'claude-code', status: 'pass', detail: 'Claude Code: hippo plugin enabled (all hooks, including compaction and failed-tool capture)' });
+        }
+        else if (missing.length === 0) {
+            checks.push({ id: 'claude-code', status: 'pass', detail: 'Claude Code: all hippo hooks installed, including compaction and failed-tool capture' });
+        }
+        else if (missing.length === hooks.length) {
+            checks.push({ id: 'claude-code', status: 'warn', detail: 'Claude Code found, but no hippo hooks are installed', fix: 'hippo hook install claude-code' });
+        }
+        else {
+            checks.push({ id: 'claude-code', status: 'warn', detail: `Claude Code: hippo hooks missing for ${missing.join(', ')}`, fix: 'hippo hook install claude-code   (adds only what is missing)' });
+        }
+    }
+    else {
+        checks.push({ id: 'claude-code', status: 'info', detail: 'Claude Code not found; other agents can use hippo over MCP (hippo mcp)' });
+    }
+    checks.push({ id: 'embeddings', status: 'info', detail: isEmbeddingAvailable() ? 'local embeddings available (hybrid search)' : 'embeddings not installed; recall uses BM25 (optional: hippo embed --help)' });
+    return { ok: !checks.some((c) => c.status === 'fail'), version: opts.version, store, checks };
+}
+/** Human-readable rendering of a {@link DoctorReport}. */
+export function formatDoctor(report) {
+    const mark = { pass: 'ok  ', warn: 'warn', fail: 'FAIL', info: 'info' };
+    const lines = [`hippo ${report.version} doctor`, ''];
+    for (const c of report.checks) {
+        lines.push(`  [${mark[c.status]}] ${c.id.padEnd(11)} ${c.detail}`);
+        if (c.fix && (c.status === 'warn' || c.status === 'fail'))
+            lines.push(`         ${''.padEnd(11)} fix: ${c.fix}`);
+    }
+    lines.push('', report.ok ? 'No failures.' : 'Some checks failed; run the fix commands above.');
+    return lines.join('\n');
+}
+//# sourceMappingURL=doctor.js.map