hippo-memory 1.69.0 → 1.71.0

package/dist/db/wal-checkpointer.js

@@ -0,0 +1,92 @@
+// A served store's WAL is checkpointed on a worker thread: the fsync calls of a checkpoint would otherwise stall every request on the event loop.
+import * as path from 'node:path';
+import { Worker } from 'node:worker_threads';
+import { errorMessage, log } from '../util/log.js';
+// WAL pages at which a connection checkpoints inside its own commit.
+const INLINE_CHECKPOINT_PAGES = 100;
+// The same limit while a worker checkpoints the store: SQLite still bounds the WAL when the worker falls behind.
+const BACKSTOP_CHECKPOINT_PAGES = 4000;
+// Sized so one background checkpoint covers about 1000 WAL pages of recalls, SQLite's own default.
+const RESPONSES_PER_CHECKPOINT = 32;
+// After a checkpoint that left frames behind, a sooner retry keeps what an inline checkpoint would have to flush small.
+const RESPONSES_PER_RETRY = 8;
+// A commit that lands during a pass leaves frames behind, and only a WAL with none left can be reused from its start.
+const MAX_PASSES = 4;
+// CommonJS in a string, so the worker starts the same way from dist, vitest and strip-types, with no second entry file.
+const WORKER_SOURCE = `
+const { parentPort, workerData } = require('node:worker_threads');
+const { DatabaseSync } = require('node:sqlite');
+const db = new DatabaseSync(workerData.dbPath);
+db.exec('PRAGMA busy_timeout = 5000');
+db.exec('PRAGMA synchronous = NORMAL');
+const pass = db.prepare('PRAGMA wal_checkpoint(PASSIVE)');
+parentPort.on('message', (message) => {
+  if (message === 'stop') {
+    db.close();
+    parentPort.close();
+    return;
+  }
+  let seen = -1;
+  let settled = false;
+  for (let n = 0; n < workerData.maxPasses && !settled; n++) {
+    const { busy, log, checkpointed } = pass.get();
+    if (busy) break;
+    settled = log === seen && checkpointed === log;
+    seen = log;
+  }
+  parentPort.postMessage(settled);
+});
+`;
+const backgrounded = new Set();
+/** The wal_autocheckpoint value for a new connection to `dbPath` in this process. */
+export function autoCheckpointPages(dbPath) {
+    return backgrounded.has(path.resolve(dbPath)) ? BACKSTOP_CHECKPOINT_PAGES : INLINE_CHECKPOINT_PAGES;
+}
+/** Checkpoints `dbPath` off the calling thread until `stop()`; the worker starts with the first checkpoint that is due. */
+export function startWalCheckpointer(dbPath) {
+    const key = path.resolve(dbPath);
+    let worker;
+    let exited;
+    let running = false;
+    let stopped = false;
+    let responses = 0;
+    let due = RESPONSES_PER_CHECKPOINT;
+    backgrounded.add(key);
+    const end = () => {
+        stopped = true;
+        backgrounded.delete(key);
+    };
+    const spawn = () => {
+        // An explicit execArgv keeps the parent's loaders out of the worker and silences its repeat of the node:sqlite warning.
+        const started = new Worker(WORKER_SOURCE, { eval: true, execArgv: ['--no-warnings'], workerData: { dbPath: key, maxPasses: MAX_PASSES } });
+        started.unref();
+        started.on('message', (settled) => {
+            running = false;
+            due = settled ? RESPONSES_PER_CHECKPOINT : RESPONSES_PER_RETRY;
+        });
+        started.on('error', (err) => {
+            end();
+            log.warn(`background checkpoint of ${key} stopped (${errorMessage(err)}); each connection checkpoints inside its own commit again`);
+        });
+        exited = new Promise((resolve) => { started.once('exit', () => resolve()); });
+        return started;
+    };
+    return {
+        noteResponse() {
+            if (stopped || ++responses < due || running)
+                return;
+            responses = 0;
+            running = true;
+            worker ??= spawn();
+            worker.postMessage('checkpoint');
+        },
+        async stop() {
+            const live = !stopped;
+            end();
+            if (live)
+                worker?.postMessage('stop');
+            await exited;
+        },
+    };
+}
+//# sourceMappingURL=wal-checkpointer.js.map

package/dist/doctor.js

@@ -1,24 +1,23 @@
-/**
- * `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.
- */
+/** `hippo doctor`: a read-only health check (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 { findHippoStoreDir } from './core/project-identity.js';
+import { getGlobalRoot } from './sharing/global-store.js';
 import { isInitialized } from './store/open.js';
-import { loadConfig } from './config.js';
-import { openHippoDbReadOnly, closeHippoDb, getSchemaVersion, getCurrentSchemaVersion, countTableRows, ftsRowCounts, IncompatibleBinaryError } from './db.js';
-import { REPLAY_AFTER_MS, TRANSCRIPT_FILL_WINDOW_MS } from './compaction-record.js';
-import { SPOOL_DIR, spoolCounts } from './compaction-spool.js';
-import { isEmbeddingAvailable } from './local-embedding.js';
-import { CODEX_TRUST_LINE, claudeConfigDir, codexHomeDir, isCodexPresent, isJsonObject } from './hooks/shared.js';
-import { planProjectRepair } from './project-merge.js';
-import { resolveTenantId } from './tenant.js';
-import { readJsonFile } from './json.js';
+import { readStoreHealth } from './store/diagnostics.js';
+import { loadConfig } from './core/config.js';
+import { openHippoDbReadOnly, closeHippoDb, getCurrentSchemaVersion, IncompatibleBinaryError } from './db/index.js';
+import { REPLAY_AFTER_MS, TRANSCRIPT_FILL_WINDOW_MS } from './capture/compaction-record.js';
+import { SPOOL_DIR, spoolCounts } from './capture/compaction-spool.js';
+import { isEmbeddingAvailable } from './store/embeddings/local.js';
+import { CODEX_TRUST_LINE, claudeConfigDir, codexHomeDir, isCodexPresent } from './hooks/shared.js';
+import { planProjectRepair } from './sharing/project-merge.js';
+import { resolveTenantId } from './store/tenant.js';
+import { errorMessage, log } from './util/log.js';
+import { readJsonFile, isJsonObjectLiteral } from './util/json.js';
+import { DAY_MS } from './util/time.js';
 /** Minimum Node.js version hippo supports (package.json engines). */
 export const MIN_NODE = '22.16.0';
 function versionAtLeast(actual, min) {
@@ -46,8 +45,13 @@ function codexCheck(home) {
     const file = path.join(codexHomeDir(home), 'hooks.json');
     const parsed = readJson(file);
     // Codex drops every hook in a hooks.json it cannot parse, hippo's included.
-    if (fs.existsSync(file) && !isJsonObject(parsed)) {
-        return { id: 'codex', status: 'warn', detail: "Codex's hooks.json is not a JSON object, so Codex runs no hook from it", fix: 'repair hooks.json, then run: hippo hook install codex' };
+    if (fs.existsSync(file) && !isJsonObjectLiteral(parsed)) {
+        return {
+            id: 'codex',
+            status: 'warn',
+            detail: "Codex's hooks.json is not a JSON object, so Codex runs no hook from it",
+            fix: 'repair hooks.json, then run: hippo hook install codex'
+        };
     }
     const text = JSON.stringify(parsed ?? '');
     const codexHooks = [
@@ -60,47 +64,44 @@ function codexCheck(home) {
     return {
         id: 'codex',
         status: 'warn',
-        detail: missing.length === codexHooks.length ? "Codex found, but hippo's memory hooks are not installed" : `Codex: hippo hooks missing for ${missing.join(', ')}`,
+        detail: missing.length === codexHooks.length
+            ? "Codex found, but hippo's memory hooks are not installed"
+            : `Codex: hippo hooks missing for ${missing.join(', ')}`,
         fix: 'hippo hook install codex   (then trust the hooks once in /hooks)',
     };
 }
 // Migration 46 creates failure_log; a read-only open no longer creates it on an older store.
 const FAILURE_LOG_SCHEMA = 46;
 /** The failed-tool-call count over the last 7 days, or why it could not be read. */
-function failuresCheck(db, since, schemaVersion) {
-    try {
-        // SAFETY: COUNT aggregate row.
-        const row = db.prepare(`SELECT COUNT(*) AS n FROM failure_log WHERE ts >= ?`).get(since);
-        return { id: 'failures', status: 'info', detail: `${Number(row?.n ?? 0)} failed tool calls logged in 7 days (hippo failures for detail)` };
+function failuresCheck(failures, schemaVersion) {
+    if (failures.ok) {
+        return { id: 'failures', status: 'info', detail: `${failures.value} failed tool calls logged in 7 days (hippo failures for detail)` };
     }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        if (!message.includes('no such table')) {
-            return { id: 'failures', status: 'warn', detail: `cannot read the failure log: ${message}` };
-        }
-        return schemaVersion < FAILURE_LOG_SCHEMA
-            ? { id: 'failures', status: 'info', detail: 'no failure log yet (hippo creates it on the next write)' }
-            : { id: 'failures', status: 'warn', detail: 'the failure_log table is missing, so failed tool calls are not being logged' };
+    if (!failures.message.includes('no such table')) {
+        return { id: 'failures', status: 'warn', detail: `cannot read the failure log: ${failures.message}` };
     }
+    return schemaVersion < FAILURE_LOG_SCHEMA
+        ? { id: 'failures', status: 'info', detail: 'no failure log yet (hippo creates it on the next write)' }
+        : { id: 'failures', status: 'warn', detail: 'the failure_log table is missing, so failed tool calls are not being logged' };
 }
 /** How long ago the store last slept (consolidated), or why that history could not be read. */
-function sleepCheck(db, now) {
-    try {
-        // SAFETY: row's shape matches the single `timestamp` column named in the SELECT above.
-        const row = db.prepare(`SELECT timestamp FROM consolidation_runs ORDER BY timestamp DESC, id DESC LIMIT 1`).get();
-        const when = row?.timestamp !== undefined ? Date.parse(row.timestamp) : Number.NaN;
-        if (Number.isNaN(when)) {
-            return { id: 'sleep', status: 'warn', detail: 'hippo has never slept (consolidated) in this store', fix: 'hippo sleep   (the session-end hook runs it automatically)' };
-        }
-        const days = Math.floor((now.getTime() - when) / 86_400_000);
-        return 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 (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return { id: 'sleep', status: 'info', detail: `sleep history unavailable (${message})` };
+function sleepCheck(lastSleep, now) {
+    if (!lastSleep.ok)
+        return { id: 'sleep', status: 'info', detail: `sleep history unavailable (${lastSleep.message})` };
+    const last = lastSleep.value;
+    const when = last !== undefined ? Date.parse(last) : Number.NaN;
+    if (Number.isNaN(when)) {
+        return {
+            id: 'sleep',
+            status: 'warn',
+            detail: 'hippo has never slept (consolidated) in this store',
+            fix: 'hippo sleep   (the session-end hook runs it automatically)'
+        };
     }
+    const days = Math.floor((now.getTime() - when) / DAY_MS);
+    return 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`}` };
 }
 /** Spool counts in their own try, so a spool that cannot be read never hides the database counts. */
 function readSpool(store, now) {
@@ -108,44 +109,32 @@ function readSpool(store, now) {
         return { counts: spoolCounts(store, now, REPLAY_AFTER_MS), unread: '' };
     }
     catch (err) {
-        return { counts: { waiting: 0, stale: 0, bad: 0 }, unread: `; spool not read: ${err instanceof Error ? err.message : String(err)}` };
+        return { counts: { waiting: 0, stale: 0, bad: 0 }, unread: `; spool not read: ${errorMessage(err)}` };
     }
 }
 /** Compaction records the PostCompact hook left unfinished and spool files a replay has not finished, which `hippo sleep` replays. */
-function compactionsCheck(db, store, now) {
-    const stuckBefore = new Date(now.getTime() - REPLAY_AFTER_MS).toISOString();
-    const transcriptFloor = new Date(now.getTime() - TRANSCRIPT_FILL_WINDOW_MS).toISOString();
-    try {
-        // SAFETY: COUNT aggregate row.
-        const row = db.prepare(`SELECT COUNT(*) AS total,
-              COUNT(CASE WHEN status = 'summarised' AND summarised_at < ? THEN 1 END) AS summarised,
-              COUNT(CASE WHEN status = 'started' AND started_at < ? AND started_at > ? AND transcript_path IS NOT NULL THEN 1 END) AS started
-       FROM compactions`).get(stuckBefore, stuckBefore, transcriptFloor);
-        const total = Number(row?.total ?? 0);
-        const summarised = Number(row?.summarised ?? 0);
-        const started = Number(row?.started ?? 0);
-        const stuck = summarised + started;
-        const { counts: spool, unread } = readSpool(store, now);
-        const spooled = spool.waiting + spool.stale + spool.bad > 0;
-        const recorded = `${total} compaction${total === 1 ? '' : 's'} recorded, none stuck`;
-        if (stuck === 0 && !spooled && unread === '')
-            return { id: 'compactions', status: 'pass', detail: recorded };
-        const fix = [
-            stuck + spool.waiting + spool.stale > 0 ? 'hippo sleep   (replays them)' : '',
-            spool.bad > 0 ? `open the .bad files in ${path.join(store, SPOOL_DIR)}, save what you still need with hippo remember, then delete them` : '',
-        ].filter((s) => s !== '');
-        const unfinished = stuck === 0
-            ? `${recorded} in the store`
-            : `${stuck} compaction${stuck === 1 ? '' : 's'} unfinished after 10 minutes (${summarised} with a summary whose memories are not saved yet, ${started} with no summary yet)`;
-        const note = spooled ? `; spool: ${spool.waiting} waiting, ${spool.stale} left by a replay that stopped, ${spool.bad} .bad` : '';
-        return { id: 'compactions', status: 'warn', detail: `${unfinished}${note}${unread}`, fix: fix.join('; ') };
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return message.includes('no such table')
+function compactionsCheck(compactions, store, now) {
+    if (!compactions.ok) {
+        return compactions.message.includes('no such table')
             ? { id: 'compactions', status: 'info', detail: 'no compaction records yet (hippo creates them on the next write)' }
-            : { id: 'compactions', status: 'warn', detail: `cannot read the compaction records: ${message}` };
-    }
+            : { id: 'compactions', status: 'warn', detail: `cannot read the compaction records: ${compactions.message}` };
+    }
+    const { total, summarised, started } = compactions.value;
+    const stuck = summarised + started;
+    const { counts: spool, unread } = readSpool(store, now);
+    const spooled = spool.waiting + spool.stale + spool.bad > 0;
+    const recorded = `${total} compaction${total === 1 ? '' : 's'} recorded, none stuck`;
+    if (stuck === 0 && !spooled && unread === '')
+        return { id: 'compactions', status: 'pass', detail: recorded };
+    const fix = [
+        stuck + spool.waiting + spool.stale > 0 ? 'hippo sleep   (replays them)' : '',
+        spool.bad > 0 ? `open the .bad files in ${path.join(store, SPOOL_DIR)}, save what you still need with hippo remember, then delete them` : '',
+    ].filter((s) => s !== '');
+    const unfinished = stuck === 0
+        ? `${recorded} in the store`
+        : `${stuck} compaction${stuck === 1 ? '' : 's'} unfinished after 10 minutes (${summarised} with a summary whose memories are not saved yet, ${started} with no summary yet)`;
+    const note = spooled ? `; spool: ${spool.waiting} waiting, ${spool.stale} left by a replay that stopped, ${spool.bad} .bad` : '';
+    return { id: 'compactions', status: 'warn', detail: `${unfinished}${note}${unread}`, fix: fix.join('; ') };
 }
 /** Old project tags in the global store, counted by the repair's own plan so a truly user-global merge never warns. */
 function projectsCheck(globalRoot) {
@@ -156,15 +145,22 @@ function projectsCheck(globalRoot) {
         const found = [
             r.copies.length > 0 ? `${r.copies.length} imported notes copied under the wrong project` : '',
             r.folds.length > 0 ? `old project names that now resolve to another project: ${r.folds.map((f) => `${f.from} -> ${f.into}`).join(', ')}` : '',
-            r.collisions.length > 0 ? `old project names shared by several projects, folded by hand only: ${r.collisions.map((c) => `${c.name} (${c.ids.join(', ')})`).join('; ')}` : '',
+            r.collisions.length > 0
+                ? `old project names shared by several projects, folded by hand only: ${r.collisions.map((c) => `${c.name} (${c.ids.join(', ')})`).join('; ')}`
+                : '',
             r.toProject.length + r.setAside.length > 0 ? `${r.toProject.length + r.setAside.length} merged memories tagged user-global` : '',
         ].filter((s) => s !== '');
         return found.length === 0
             ? { id: 'projects', status: 'pass', detail: 'no duplicate or out-of-date project tags in the global store' }
-            : { id: 'projects', status: 'warn', detail: `global store: ${found.join('; ')}`, fix: 'hippo projects repair --global   (dry run; add --apply to write)' };
+            : {
+                id: 'projects',
+                status: 'warn',
+                detail: `global store: ${found.join('; ')}`,
+                fix: 'hippo projects repair --global   (dry run; add --apply to write)'
+            };
     }
     catch (err) {
-        return { id: 'projects', status: 'info', detail: `project tags not checked (${err instanceof Error ? err.message : String(err)})` };
+        return { id: 'projects', status: 'info', detail: `project tags not checked (${errorMessage(err)})` };
     }
     finally {
         if (db !== null)
@@ -179,16 +175,43 @@ function nodeCheck(node) {
 /** The store the checks run against (project first, then global), and the check that says which. */
 function storeCheck(local, globalRoot, hasGlobal) {
     if (local !== null && isInitialized(local)) {
-        return { store: local, check: { id: 'store', status: 'pass', detail: `project store at ${local}${hasGlobal ? ` (global store at ${globalRoot} too)` : ''}` } };
+        return {
+            store: local,
+            check: { id: 'store', status: 'pass', detail: `project store at ${local}${hasGlobal ? ` (global store at ${globalRoot} too)` : ''}` }
+        };
     }
     if (local !== null) {
         // The walk stops at the first .hippo it finds, so a bare one (no hippo.db) blocks a parent or global store too.
-        return { store: null, check: { id: 'store', status: 'fail', detail: `${local} has no hippo.db, so hippo commands run here stop at it`, fix: `run hippo init in ${path.dirname(local)}, or remove that .hippo folder` } };
+        return {
+            store: null,
+            check: {
+                id: 'store',
+                status: 'fail',
+                detail: `${local} has no hippo.db, so hippo commands run here stop at it`,
+                fix: `run hippo init in ${path.dirname(local)}, or remove that .hippo folder`
+            }
+        };
     }
     if (hasGlobal) {
-        return { store: globalRoot, check: { id: 'store', status: 'warn', detail: `no project store here; using the global store at ${globalRoot}`, fix: 'hippo init   (in the project root)' } };
+        return {
+            store: globalRoot,
+            check: {
+                id: 'store',
+                status: 'warn',
+                detail: `no project store here; using the global store at ${globalRoot}`,
+                fix: 'hippo init   (in the project root)'
+            }
+        };
     }
-    return { store: null, check: { id: 'store', status: 'fail', detail: 'no hippo store found (project or global)', fix: 'hippo init   (in the project root), or hippo init --global' } };
+    return {
+        store: null,
+        check: {
+            id: 'store',
+            status: 'fail',
+            detail: 'no hippo store found (project or global)',
+            fix: 'hippo init   (in the project root), or hippo init --global'
+        }
+    };
 }
 function schemaCheck(have, want) {
     return have === want
@@ -197,9 +220,7 @@ function schemaCheck(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` };
 }
-function memoriesCheck(db) {
-    const memories = countTableRows(db, 'memories');
-    const dormant = countTableRows(db, 'dormant_memories');
+function memoriesCheck(memories, dormant) {
     const memoryCheck = { id: 'memories', status: 'info', detail: `${memories ?? '?'} memories${dormant !== null ? `, ${dormant} dormant` : ''}` };
     if (memories === 0) {
         memoryCheck.status = 'warn';
@@ -208,70 +229,60 @@ function memoriesCheck(db) {
     return memoryCheck;
 }
 /** Whether the full-text index still matches `memories`; opening a current store no longer checks, so doctor reports and sleep repairs. */
-function ftsCheck(db) {
-    try {
-        const counts = ftsRowCounts(db);
-        if (counts === null)
-            return { id: 'fts', status: 'info', detail: 'no full-text index; search uses slower LIKE matching' };
-        if (counts.memories === counts.fts)
-            return { id: 'fts', status: 'pass', detail: `full-text index in sync (${counts.fts} rows)` };
-        return {
-            id: 'fts',
-            status: 'warn',
-            detail: `full-text index out of sync: ${counts.fts} indexed rows for ${counts.memories} memories, so search can miss memories or match removed ones`,
-            fix: 'hippo sleep   (re-syncs the index)',
-        };
-    }
-    catch (err) {
-        return { id: 'fts', status: 'warn', detail: `cannot read the full-text index: ${err instanceof Error ? err.message : String(err)}` };
-    }
+function ftsCheck(fts) {
+    if (!fts.ok)
+        return { id: 'fts', status: 'warn', detail: `cannot read the full-text index: ${fts.message}` };
+    const counts = fts.value;
+    if (counts === null)
+        return { id: 'fts', status: 'info', detail: 'no full-text index; search uses slower LIKE matching' };
+    if (counts.memories === counts.fts)
+        return { id: 'fts', status: 'pass', detail: `full-text index in sync (${counts.fts} rows)` };
+    return {
+        id: 'fts',
+        status: 'warn',
+        detail: `full-text index out of sync: ${counts.fts} indexed rows for ${counts.memories} memories, so search can miss memories or match removed ones`,
+        fix: 'hippo sleep   (re-syncs the index)',
+    };
 }
-function tokensCheck(db, since) {
-    try {
-        // SAFETY: COUNT/SUM aggregate row.
-        const row = db.prepare(`SELECT COUNT(CASE WHEN event = 'inject' THEN 1 END) AS n,
-              COALESCE(SUM(CASE WHEN event = 'inject' THEN tokens END), 0) AS t,
-              COALESCE(SUM(CASE WHEN event = 'reread' THEN tokens END), 0) AS r
-       FROM token_ledger WHERE ts >= ?`).get(since);
-        return {
-            id: 'tokens',
-            status: 'info',
-            detail: `${Number(row?.n ?? 0)} memory blocks sent to agents in 7 days, about ${Number(row?.t ?? 0)} tokens sent and ${Number(row?.r ?? 0)} re-read by later model calls (hippo tokens for detail)`,
-        };
-    }
-    catch {
+function tokensCheck(tokens) {
+    if (!tokens.ok) {
+        log.debug(`doctor: token ledger not read: ${tokens.message}`);
         return { id: 'tokens', status: 'info', detail: 'no token ledger yet (created on the next write)' };
     }
+    const tally = tokens.value;
+    return {
+        id: 'tokens',
+        status: 'info',
+        detail: `${tally.injected} memory blocks sent to agents in 7 days, about ${tally.tokensSent} tokens sent and ${tally.tokensReread} re-read by later model calls (hippo tokens for detail)`,
+    };
 }
-/** Checks that read the store's database; a failed open becomes a failed schema check after whatever already passed. */
+/** Checks that read the store's database; a store that cannot be opened becomes one failed schema check. */
 function databaseChecks(store, now) {
-    const checks = [];
-    let db = null;
+    let health;
     try {
-        db = openHippoDbReadOnly(store);
-        const have = getSchemaVersion(db);
-        checks.push(schemaCheck(have, getCurrentSchemaVersion()));
-        checks.push(memoriesCheck(db));
-        checks.push(ftsCheck(db));
-        const since = new Date(now.getTime() - 7 * 86_400_000).toISOString();
-        checks.push(tokensCheck(db, since));
-        checks.push(failuresCheck(db, since, have));
-        checks.push(sleepCheck(db, now));
-        checks.push(compactionsCheck(db, store, now));
-    }
-    catch (err) {
-        checks.push({
-            id: 'schema',
-            status: 'fail',
-            detail: `cannot open the database: ${err instanceof Error ? err.message : String(err)}`,
-            fix: err instanceof IncompatibleBinaryError ? 'npm install -g hippo-memory@latest' : 'check file permissions on the .hippo folder',
+        health = readStoreHealth(store, {
+            since: new Date(now.getTime() - 7 * DAY_MS).toISOString(),
+            stuckBefore: new Date(now.getTime() - REPLAY_AFTER_MS).toISOString(),
+            transcriptFloor: new Date(now.getTime() - TRANSCRIPT_FILL_WINDOW_MS).toISOString(),
         });
     }
-    finally {
-        if (db !== null)
-            closeHippoDb(db);
-    }
-    return checks;
+    catch (err) {
+        return [{
+                id: 'schema',
+                status: 'fail',
+                detail: `cannot open the database: ${errorMessage(err)}`,
+                fix: err instanceof IncompatibleBinaryError ? 'npm install -g hippo-memory@latest' : 'check file permissions on the .hippo folder',
+            }];
+    }
+    return [
+        schemaCheck(health.schemaVersion, getCurrentSchemaVersion()),
+        memoriesCheck(health.memories, health.dormant),
+        ftsCheck(health.fts),
+        tokensCheck(health.tokens),
+        failuresCheck(health.failures, health.schemaVersion),
+        sleepCheck(health.lastSleep, now),
+        compactionsCheck(health.compactions, store, now),
+    ];
 }
 // Each hook and what it does, so a partial install says what is missing.
 const CLAUDE_CODE_HOOKS = [
@@ -300,7 +311,12 @@ function claudeCodeCheck(home) {
     if (missing.length === CLAUDE_CODE_HOOKS.length) {
         return { id: 'claude-code', status: 'warn', detail: 'Claude Code found, but no hippo hooks are installed', fix: 'hippo hook install claude-code' };
     }
-    return { 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)' };
+    return {
+        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)'
+    };
 }
 /** Run every check. Never throws for a broken install; broken parts become failed checks. */
 export function runDoctor(opts) {
@@ -318,14 +334,22 @@ export function runDoctor(opts) {
         checks.push(...databaseChecks(store, now));
     const holdoutRateBp = store === null ? 0 : loadConfig(store).pilot.holdoutRateBp;
     if (holdoutRateBp > 0) {
-        checks.push({ id: 'pilot', status: 'info', detail: `pilot holdout on: about ${holdoutRateBp / 100}% of sessions get no memories pushed by hippo (pilot.holdoutRateBp=${holdoutRateBp})` });
+        checks.push({
+            id: 'pilot',
+            status: 'info',
+            detail: `pilot holdout on: about ${holdoutRateBp / 100}% of sessions get no memories pushed by hippo (pilot.holdoutRateBp=${holdoutRateBp})`
+        });
     }
     if (hasGlobal)
         checks.push(projectsCheck(globalRoot));
     checks.push(claudeCodeCheck(home));
     if (isCodexPresent(home))
         checks.push(codexCheck(home));
-    checks.push({ id: 'embeddings', status: 'info', detail: isEmbeddingAvailable() ? 'local embeddings available (hybrid search)' : 'embeddings not installed; recall uses BM25 (optional: hippo embed --help)' });
+    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}. */

package/dist/entry/json-hooks.d.ts

@@ -1,3 +1,3 @@
 export { installJsonHooks, resolveJsonHookPaths, uninstallJsonHooks, writeSettingsFile, type InstallResult, type JsonHookPaths } from '../hooks/json-hooks.js';
-export { readJsonFile } from '../json.js';
+export { readJsonFile } from '../util/json.js';
 //# sourceMappingURL=json-hooks.d.ts.map

package/dist/entry/json-hooks.js

@@ -1,4 +1,4 @@
 // The hippo-memory/json-hooks subpath: only what the changelog publishes, so the module's other exports stay internal.
 export { installJsonHooks, resolveJsonHookPaths, uninstallJsonHooks, writeSettingsFile } from '../hooks/json-hooks.js';
-export { readJsonFile } from '../json.js';
+export { readJsonFile } from '../util/json.js';
 //# sourceMappingURL=json-hooks.js.map

package/dist/entry/project-identity.d.ts

@@ -1,2 +1,2 @@
-export { MAX_PROJECT_ALIASES, MCP_PROJECT_SCOPED_HEADER, resolveProjectIdentity, type ProjectIdentity, type ResolveProjectIdentityOpts } from '../project-identity.js';
+export { MAX_PROJECT_ALIASES, MCP_PROJECT_SCOPED_HEADER, resolveProjectIdentity, type ProjectIdentity, type ResolveProjectIdentityOpts } from '../core/project-identity.js';
 //# sourceMappingURL=project-identity.d.ts.map

package/dist/entry/project-identity.js

@@ -1,3 +1,3 @@
 // The hippo-memory/project-identity subpath: only what the changelog publishes, so the module's other exports stay internal.
-export { MAX_PROJECT_ALIASES, MCP_PROJECT_SCOPED_HEADER, resolveProjectIdentity } from '../project-identity.js';
+export { MAX_PROJECT_ALIASES, MCP_PROJECT_SCOPED_HEADER, resolveProjectIdentity } from '../core/project-identity.js';
 //# sourceMappingURL=project-identity.js.map

package/dist/entry/session-text.d.ts

@@ -1,7 +1,7 @@
 export { collectSessionTurns, sessionTail, type SessionTurn } from '../capture/transcript.js';
-export { scrubForSharing } from '../share-scrub.js';
+export { scrubForSharing } from '../capture/share-scrub.js';
 export { transcriptWorkingState, WORKING_STATE_CAPS } from '../capture/working-state.js';
 export { lessonFromFailure, failureReport, type FailureReport } from '../capture/failure-reading.js';
-export { collectHandoffEvidence } from '../handoff-evidence.js';
-export { compactSummaryBody, parseCompactionItems, COMPACTION_ITEM_MAX_CHARS, COMPACTION_ITEM_ROW_CAP } from '../compaction-items.js';
+export { collectHandoffEvidence } from '../capture/handoff-evidence.js';
+export { compactSummaryBody, parseCompactionItems, COMPACTION_ITEM_MAX_CHARS, COMPACTION_ITEM_ROW_CAP } from '../capture/compaction-items.js';
 //# sourceMappingURL=session-text.d.ts.map

package/dist/entry/session-text.js

@@ -1,8 +1,9 @@
-// The hippo-memory/session-text subpath: what a hook reads from a session (turns, working state, failures, git state, compaction items) and the sharing scrub, with no store, database or server in its imports.
+// The hippo-memory/session-text subpath: what a hook reads from a session (turns, working state, failures,
+// git state, compaction items) and the sharing scrub, with no store, database or server in its imports.
 export { collectSessionTurns, sessionTail } from '../capture/transcript.js';
-export { scrubForSharing } from '../share-scrub.js';
+export { scrubForSharing } from '../capture/share-scrub.js';
 export { transcriptWorkingState, WORKING_STATE_CAPS } from '../capture/working-state.js';
 export { lessonFromFailure, failureReport } from '../capture/failure-reading.js';
-export { collectHandoffEvidence } from '../handoff-evidence.js';
-export { compactSummaryBody, parseCompactionItems, COMPACTION_ITEM_MAX_CHARS, COMPACTION_ITEM_ROW_CAP } from '../compaction-items.js';
+export { collectHandoffEvidence } from '../capture/handoff-evidence.js';
+export { compactSummaryBody, parseCompactionItems, COMPACTION_ITEM_MAX_CHARS, COMPACTION_ITEM_ROW_CAP } from '../capture/compaction-items.js';
 //# sourceMappingURL=session-text.js.map