hippo-memory 1.70.0 → 1.72.0

package/dist/store/audit.js

@@ -1,63 +1,9 @@
-import { createHash } from 'node:crypto';
-import { canAutoDelete } from '../core/memory.js';
+import { DEFAULT_LIST_LIMIT } from '../util/limits.js';
 import { closeHippoDb, openHippoDb, withWriteScope } from '../db/index.js';
 import { log } from '../util/log.js';
+import { blockHash } from '../util/token-text.js';
 import { keysetAfter } from '../util/keyset.js';
 import { warnDamagedColumn } from '../util/stored-json.js';
-import { automaticDefect, hasNoSpecificity, isFragment, isReleaseCommitNoise, substantiveWordCount, } from '../core/memory-quality.js';
-export function auditMemory(entry, backsObject = false) {
-    const issue = classifyMemory(entry);
-    // Error means "auto-remove"; a pinned, raw, kept-for-good or object-backing row is never auto-removed, so it can only warn.
-    if (issue?.severity === 'error' && (!canAutoDelete(entry) || backsObject)) {
-        const why = entry.pinned ? 'pinned' : entry.kind === 'raw' ? 'raw' : backsObject ? 'backs an object' : 'keep rule';
-        return { ...issue, severity: 'warning', reason: `${issue.reason} (${why}, kept)` };
-    }
-    return issue;
-}
-function classifyMemory(entry) {
-    const content = entry.content.trim();
-    if (content.length < 3) {
-        return { memoryId: entry.id, content, severity: 'error', reason: 'too short (< 3 chars)' };
-    }
-    if (content.length < 10) {
-        return { memoryId: entry.id, content, severity: 'error', reason: 'too short (< 10 chars)' };
-    }
-    if (isReleaseCommitNoise(content)) {
-        return { memoryId: entry.id, content, severity: 'error', reason: 'release/commit noise, not a useful memory' };
-    }
-    if (isFragment(content)) {
-        return { memoryId: entry.id, content, severity: 'warning', reason: 'sentence fragment — lacks context' };
-    }
-    const substantive = substantiveWordCount(content);
-    if (substantive < 2) {
-        return { memoryId: entry.id, content, severity: 'warning', reason: `only ${substantive} substantive word(s) — too vague` };
-    }
-    if (content.length < 40 && hasNoSpecificity(content)) {
-        return { memoryId: entry.id, content, severity: 'warning', reason: 'no specific details (names, paths, numbers, code)' };
-    }
-    const reason = automaticDefect(entry);
-    if (reason !== null) {
-        return { memoryId: entry.id, content, severity: 'warning', reason: `automatic memory defect: ${reason}` };
-    }
-    return null;
-}
-/** `backing`: ids of memories that back an object (store.memoriesBackingObjects). */
-export function auditMemories(entries, backing) {
-    const issues = [];
-    for (const entry of entries) {
-        const issue = auditMemory(entry, backing.has(entry.id));
-        if (issue)
-            issues.push(issue);
-    }
-    return {
-        total: entries.length,
-        issues,
-        clean: entries.length - issues.length,
-    };
-}
-// ---------------------------------------------------------------------------
-// Audit log primitives (append-only mutation trail)
-// ---------------------------------------------------------------------------
 // The one list of audit ops: the AuditOp type, `hippo audit list --op` and GET /v1/audit?op= all read it.
 export const AUDIT_OPS = [
     'remember',
@@ -131,7 +77,7 @@ function bigintSafeReplacer(_key, value) {
 }
 export function auditQueryFields(query) {
     return {
-        query_hash: createHash('sha256').update(query).digest('hex').slice(0, 16),
+        query_hash: blockHash(query),
         query_length: query.length,
     };
 }
@@ -175,18 +121,15 @@ export function queryAuditEvents(db, opts) {
     }
     const after = keysetAfter('ts', 'id', opts.after);
     // One past the route's 10000 cap: GET /v1/audit reads a row ahead to tell whether another page exists.
-    const limit = Math.max(1, Math.min(opts.limit ?? 100, 10001));
+    const limit = Math.max(1, Math.min(opts.limit ?? DEFAULT_LIST_LIMIT, 10001));
     // SAFETY: AUDIT_COLUMNS names exactly the AuditRow columns, in this order.
     const rows = db
         .prepare(`SELECT ${AUDIT_COLUMNS} FROM audit_log WHERE ${where.join(' AND ')}${after.sql} ORDER BY ts DESC, id DESC LIMIT ?`)
         .all(...params, ...after.params, limit);
     return rows.map(rowToAuditEvent);
 }
-/**
- * Cursor read: events with id > afterId, ascending by id. Ids are AUTOINCREMENT
- * and never reused, but deletes (retention prune) leave gaps, so resume from
- * the last id returned, never from a count.
- */
+/** Cursor read: events with id > afterId, ascending. Retention prune leaves gaps in the ids,
+ * so resume from the last id returned, never from a count. */
 export function listAuditEventsAfter(db, opts) {
     if (!Number.isInteger(opts.afterId) || opts.afterId < 0) {
         throw new RangeError('afterId must be a non-negative integer');
@@ -255,10 +198,8 @@ function rowToAuditEvent(r) {
 function safeJsonParse(raw, id) {
     try {
         const v = JSON.parse(raw);
-        // SAFETY: JSON.parse only ever returns a plain object, array, string, number,
-        // boolean, or null; `v instanceof Object` is true for exactly the first two
-        // (both are valid JsonObject shapes for our purposes), matching the prior
-        // `typeof v === 'object' && v !== null` check without using typeof.
+        // SAFETY: JSON.parse returns only an object, array or primitive; `instanceof Object` is true for the first two,
+        // both valid JsonObject shapes here.
         return v instanceof Object ? v : {};
     }
     catch {

package/dist/store/auth.d.ts

@@ -12,13 +12,15 @@ export declare function apiKeyVerifyStats(): ApiKeyVerifyStats;
 export interface CreateApiKeyOpts {
     tenantId: string;
     label?: string;
-    /** 'admin' | 'member'. Defaults to 'admin' (backward-compat for callers that don't specify). */
+    /** 'admin' | 'member'. Defaults to 'member', like the API layer. */
     role?: 'admin' | 'member';
     /** The auth-resolver subject a self-service key belongs to; unset for keys an admin or the CLI mints. */
     ownerSubject?: string;
-    /** ISO time the key stops working; unset means it never expires. */
+    /** ISO time the key stops working; unset means DEFAULT_KEY_TTL_DAYS from now. */
     expiresAt?: string;
 }
+/** Days a key lives when its mint names no expiry, so a key nobody remembers stops working by itself. */
+export declare const DEFAULT_KEY_TTL_DAYS = 90;
 export interface CreateApiKeyResult {
     keyId: string;
     plaintext: string;
@@ -75,7 +77,8 @@ export interface ApiKeyRecord {
 /** The api_keys row for `keyId` with its scope grants; null when no row matches. */
 export declare function readApiKeyRecord(db: DatabaseSyncLike, keyId: string): ApiKeyRecord | null;
 export declare function validateApiKey(db: DatabaseSyncLike, plaintext: string): ValidateResult;
-/** LRU of the tokens that matched a stored key hash, so a repeat skips scrypt. Holds a SHA-256 of the token, never the token, and nothing about the key's state. */
+/** LRU of the tokens that matched a stored key hash, so a repeat skips scrypt. Holds
+ * a SHA-256 of the token, never the token, and nothing about the key's state. */
 export declare class VerifiedKeyCache {
     private readonly capacity;
     private readonly proven;
@@ -86,7 +89,8 @@ export declare class VerifiedKeyCache {
 }
 /** A caller's limit on scrypt work, called once per derivation: it may throw to refuse `derive` or hold it in a queue. */
 type DerivationBound = (keyId: string, derive: () => Promise<Buffer>) => Promise<Buffer>;
-/** Verify a bearer API key against `store`, null when invalid. The key's row is read on every call, so a revoke, expiry, role or scope change by any process applies on the next one. */
+/** Verify a bearer API key against `store`, null when invalid. The key's row is read on every
+ * call, so a revoke, expiry, role or scope change by any process applies on the next one. */
 export declare function verifyApiKeyCached(plaintext: string, store: HippoStore, bound?: DerivationBound): Promise<VerifiedApiKey | null>;
 export declare function revokeApiKey(db: DatabaseSyncLike, keyId: string, at?: string): void;
 /** Grant `keyId` read access to one restricted `scope`. Idempotent. */
@@ -99,10 +103,8 @@ export interface ApiKeyListItem {
     label: string | null;
     createdAt: string;
     revokedAt: string | null;
-    /**
-     * Authorization role bound to the key, from the `role` column (schema migration v26).
-     * Fail-safe-to-member cast: any non-'admin' value reads as 'member'.
-     */
+    /** Authorization role from the `role` column (schema migration v26).
+     * Fail-safe cast: any non-'admin' value reads as 'member'. */
     role: 'admin' | 'member';
     /** Restricted scopes this key may read. */
     scopes: string[];

package/dist/store/auth.js

@@ -3,6 +3,7 @@ import { promisify } from 'node:util';
 import { closeHippoDb, openHippoDb } from '../db/index.js';
 import { raiseMinBinary } from '../db/meta.js';
 import { keysetAfter } from '../util/keyset.js';
+import { DAY_MS } from '../util/time.js';
 import { EXPIRING_KEYS_MIN_BINARY } from '../util/version.js';
 /** Every minted API key starts with this, so the server can route a bearer token by shape. */
 export const API_KEY_PREFIX = 'hk_';
@@ -48,15 +49,16 @@ function verifyKey(plaintext, stored) {
     return parsed.matches(scryptSync(plaintext, parsed.salt, parsed.keylen));
 }
 const scryptOffLoop = promisify(scrypt);
+/** Days a key lives when its mint names no expiry, so a key nobody remembers stops working by itself. */
+export const DEFAULT_KEY_TTL_DAYS = 90;
 export function mintApiKey() {
     const keyId = `${API_KEY_PREFIX}${randBase32(ID_LEN)}`;
     const plaintext = `${keyId}.${randBase32(SECRET_LEN)}`;
     return { keyId, plaintext, keyHash: hashKey(plaintext) };
 }
 export function insertApiKey(db, key) {
-    // openHippoDb runs runMigrations synchronously before returning the db handle,
-    // so migration v26 (adds role column) is in place before this INSERT runs.
-    // An older binary ignores expires_at and would honour an expired key, so the store shuts it out before the first one exists.
+    // Migration v26 (role column) has already run; an older binary ignores expires_at and would honour an expired key,
+    // so the store shuts it out before the first one exists.
     if (key.expiresAt !== null)
         raiseMinBinary(db, EXPIRING_KEYS_MIN_BINARY);
     db.prepare(`INSERT INTO api_keys (key_id, key_hash, tenant_id, label, created_at, role, owner_subject, expires_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(key.keyId, key.keyHash, key.tenantId, key.label, key.createdAt, key.role, key.ownerSubject, key.expiresAt);
@@ -64,16 +66,15 @@ export function insertApiKey(db, key) {
 export function createApiKey(db, opts) {
     const { keyId, plaintext, keyHash } = mintApiKey();
     insertApiKey(db, {
-        keyId, keyHash, tenantId: opts.tenantId, label: opts.label ?? null, role: opts.role ?? 'admin', createdAt: new Date().toISOString(),
-        ownerSubject: opts.ownerSubject ?? null, expiresAt: opts.expiresAt ?? null,
+        keyId, keyHash, tenantId: opts.tenantId, label: opts.label ?? null, role: opts.role ?? 'member', createdAt: new Date().toISOString(),
+        ownerSubject: opts.ownerSubject ?? null, expiresAt: opts.expiresAt ?? new Date(Date.now() + DEFAULT_KEY_TTL_DAYS * DAY_MS).toISOString(),
     });
     return { keyId, plaintext };
 }
 /** The api_keys row for `keyId` with its scope grants; null when no row matches. */
 export function readApiKeyRecord(db, keyId) {
-    // SAFETY: row comes from the SELECT above, which projects exactly
-    // key_hash, tenant_id, revoked_at, role, expires_at, owner_subject; `.get` returns undefined when no
-    // row matches key_id.
+    // SAFETY: row comes from the SELECT above, which projects exactly key_hash, tenant_id, revoked_at, role, expires_at, owner_subject;
+    // `.get` returns undefined when no row matches key_id.
     const row = db
         .prepare(`SELECT key_hash, tenant_id, revoked_at, role, expires_at, owner_subject FROM api_keys WHERE key_id = ?`)
         .get(keyId);
@@ -84,7 +85,8 @@ export function readApiKeyRecord(db, keyId) {
         expiresAt: row.expires_at, ownerSubject: row.owner_subject,
     };
 }
-/** When a key stops working, in epoch ms: Infinity for null, and already past for a missing field (a store that predates expiry) or a stamp that does not parse, so both fail closed. */
+/** When a key stops working, in epoch ms: Infinity for null, and already past for a missing
+ * field (a store that predates expiry) or a stamp that does not parse, so both fail closed. */
 function keyExpiryMs(expiresAt) {
     if (expiresAt === null)
         return Infinity;
@@ -130,7 +132,8 @@ const VERIFIED_KEY_CACHE_CAP = 1_000;
 function secretDigest(plaintext) {
     return createHash('sha256').update(plaintext).digest();
 }
-/** LRU of the tokens that matched a stored key hash, so a repeat skips scrypt. Holds a SHA-256 of the token, never the token, and nothing about the key's state. */
+/** LRU of the tokens that matched a stored key hash, so a repeat skips scrypt. Holds
+ * a SHA-256 of the token, never the token, and nothing about the key's state. */
 export class VerifiedKeyCache {
     capacity;
     // Keyed on the stored hash, so a rotated or re-minted key never meets an old entry; Map order makes the first key the least recent.
@@ -192,7 +195,8 @@ async function secretMatches(keyId, plaintext, keyHash, bound) {
     void check.then(forget, forget);
     return check;
 }
-/** Verify a bearer API key against `store`, null when invalid. The key's row is read on every call, so a revoke, expiry, role or scope change by any process applies on the next one. */
+/** Verify a bearer API key against `store`, null when invalid. The key's row is read on every
+ * call, so a revoke, expiry, role or scope change by any process applies on the next one. */
 export async function verifyApiKeyCached(plaintext, store, bound) {
     const keyId = mintedKeyId(plaintext);
     if (keyId === null)
@@ -250,7 +254,8 @@ export function listApiKeyRows(db, opts) {
     const limitSql = opts.limit === undefined ? '' : ' LIMIT ?';
     if (opts.limit !== undefined)
         params.push(opts.limit);
-    const sql = `SELECT id, key_id, tenant_id, label, created_at, revoked_at, role, expires_at, owner_subject FROM api_keys WHERE ${where.join(' AND ')}${after.sql} ORDER BY id DESC${limitSql}`;
+    const sql = `SELECT id, key_id, tenant_id, label, created_at, revoked_at, role, expires_at, owner_subject FROM api_keys ` +
+        `WHERE ${where.join(' AND ')}${after.sql} ORDER BY id DESC${limitSql}`;
     // SAFETY: the SELECT above projects exactly these 9 columns, in this order.
     const rows = db.prepare(sql).all(...params);
     return rows.map(r => ({

package/dist/store/candidates.d.ts

@@ -1,5 +1,5 @@
-import { type MemoryEntry } from '../core/memory.js';
-import { type SqlFragment } from './recall-scope.js';
+import { type MemoryEntry, type ConfidenceLevel, Layer } from '../core/memory.js';
+import { type SqlFragment } from './rule-sql.js';
 export interface AmbientRecallRequest {
     terms: string[];
     limit: number;
@@ -32,12 +32,13 @@ export declare function loadContextCandidates(hippoRoot: string, tenantId: strin
 export type HeldText = Pick<MemoryEntry, 'content' | 'source' | 'origin_project'>;
 /** Admits every scope, for a reader that sees the whole store, such as the CLI on its own machine. */
 export declare const EVERY_SCOPE: SqlFragment;
-/** Text, source and origin of tenant rows holding any of `words` that `admit` passes, by default the team-visible ones; a row equal to a text apart from spacing holds its every word.
- *  With `project`, only rows carrying one of those names and user-global rows, as loadContextCandidates' filter. No `tenantId` reads every tenant. */
+/** Tenant rows holding any of `words` that `admit` passes (default: team-visible); a row equal to a text apart from spacing holds its every word.
+ * With `project`, only rows carrying one of those names plus user-global rows, as loadContextCandidates' filter. No `tenantId` reads every tenant. */
 export declare function loadTextsHoldingWords(hippoRoot: string, tenantId: string | undefined, words: readonly string[], project?: readonly string[], admit?: SqlFragment): HeldText[];
 /** A tenant's `limit` newest rows, oldest first: the tail of loadAllEntries' order, without reading the rows before it. */
 export declare function loadNewestEntries(hippoRoot: string, tenantId: string, limit: number): MemoryEntry[];
-/** computeSchemaFit against every row of a tenant: tag counts come from one aggregate and texts stream one column, so no row is loaded. */
+/** computeSchemaFit against a tenant's newest SCHEMA_FIT_WINDOW_ROWS rows: tag counts come from one aggregate
+ * and texts stream one column, so no row is loaded. */
 export declare function schemaFitInStore(hippoRoot: string, tenantId: string, content: string, tags: readonly string[]): number;
 export interface SourceTally {
     source: string;
@@ -61,4 +62,21 @@ export interface StrengthTallies {
 }
 /** calculateStrength over every row of a tenant in one aggregate pass, no row loaded. */
 export declare function loadStrengthTallies(hippoRoot: string, tenantId: string, now: Date, atRiskBelow: number): StrengthTallies;
+/** What `hippo status` prints about the whole store: every tenant and superseded rows too. */
+export interface StatusCounts {
+    total: number;
+    byLayer: Record<Layer, number>;
+    byConfidence: Record<ConfidenceLevel, number>;
+    pinned: number;
+    /** Rows whose strength is under the caller's line; unlike StrengthTallies, pinned rows count. */
+    atRisk: number;
+    agedOut: number;
+    avgStrength: number;
+    /** Open conflicts of every tenant, the rows listMemoryConflicts returns when given no tenant. */
+    openConflicts: number;
+    /** Rows that have a stored vector. */
+    embedded: number;
+}
+/** The counts `hippo status` prints, from one pass over ten narrow columns: no text is read and no row array is built. */
+export declare function loadStatusCounts(hippoRoot: string, now: Date, atRiskBelow: number): StatusCounts;
 //# sourceMappingURL=candidates.d.ts.map

package/dist/store/candidates.js

@@ -1,45 +1,58 @@
-import { schemaFitFrom, strengthSql } from '../core/memory.js';
-import { closeHippoDb, withReadSnapshot } from '../db/index.js';
-import { scopeAdmitSql } from './recall-scope.js';
+import { FALLBACK_HALF_LIFE_DAYS, Layer, calculateStrength, facetsOf, schemaFitFrom } from '../core/memory.js';
+import { strengthSql } from './rule-sql.js';
+import { withReadSnapshot } from '../db/index.js';
+import { scopeAdmitSql } from './rule-sql.js';
 import { MEMORY_SELECT_COLUMNS, rowToEntry, parseJsonArray } from './rows.js';
-import { openStore } from './open.js';
+import { onHandle, openStore } from './open.js';
 import { originInSql } from '../core/project-identity.js';
 import { pickRarestFtsQuery, loadRecallSearchEntriesFromDb } from './search-rows.js';
 const AMBIENT_SCOPED = 'superseded_by IS NULL AND tenant_id = ?';
-/** idx_memories_pinned (db.ts v51) serves it. */
+/** idx_memories_pinned (migration v51) serves it. */
 const AMBIENT_PINNED_WHERE = `pinned = 1 AND ${AMBIENT_SCOPED} ORDER BY created ASC, id ASC`;
-/** idx_memories_created_drift (db.ts v51) serves it. */
+/** idx_memories_created_drift (migration v51) serves it. */
 const AMBIENT_DRIFT_SQL = `SELECT 1 FROM memories WHERE ${AMBIENT_SCOPED} AND (length(created) <> 24 OR created NOT LIKE '%Z') LIMIT 1`;
 function inOrigins(e, origins) {
     const origin = e.origin_project ?? null;
     return origin === '' ? origins.userGlobal : origin !== null && origins.names.includes(origin);
 }
+// `id DESC` mirrors getContext's comparator, not loadFreshRawMemories'
+// cross-ingest-stable order: that would change what the hook injects.
+const NEWEST = 'ORDER BY created DESC, id DESC';
 // The newest rows `admit` keeps, newest first. The first window stays unfiltered so admit still sees, and the
 // delivery ledger still counts, the other-project rows it refuses; past it, the reads narrow to the caller's origins.
 function loadRecentRows(run, drifted, tenantId, options) {
     const { needed, admit, origins } = options;
     const keep = origins ? (e) => admit(e) && inOrigins(e, origins) : admit;
-    // `id DESC` mirrors getContext's comparator, not loadFreshRawMemories'
-    // cross-ingest-stable order: that would change what the hook injects.
-    const newest = 'ORDER BY created DESC, id DESC';
     const window = Math.max(needed * 4, 32);
     const originSql = origins && (origins.userGlobal ? `(origin_project = '' OR ${originInSql(origins.names)})` : originInSql(origins.names));
-    const ownWhere = originSql ? `${AMBIENT_SCOPED} AND ${originSql}` : AMBIENT_SCOPED;
-    const ownParams = [tenantId, ...(origins?.names ?? [])];
-    if (!drifted) {
-        const windowed = run(`${AMBIENT_SCOPED} ${newest} LIMIT ?`, [tenantId, window]);
-        const kept = windowed.filter(keep);
-        if (kept.length >= needed || windowed.length < window)
+    const own = { where: originSql ? `${AMBIENT_SCOPED} AND ${originSql}` : AMBIENT_SCOPED, params: [tenantId, ...(origins?.names ?? [])] };
+    // Text order is chronological only for standard UTC ISO (memory.ts), so a drifted store is read whole and re-sorted downstream.
+    if (drifted)
+        return run(`${own.where} ${NEWEST}`, [...own.params]).filter(keep);
+    let read = run(`${AMBIENT_SCOPED} ${NEWEST} LIMIT ?`, [tenantId, window]);
+    let kept = read.filter(keep);
+    if (kept.length >= needed || read.length < window)
+        return kept;
+    if (origins) {
+        read = run(`${own.where} ${NEWEST} LIMIT ?`, [...own.params, window]);
+        kept = read.filter(keep);
+        if (kept.length >= needed || read.length < window)
             return kept;
-        if (origins) {
-            const ownWindow = run(`${ownWhere} ${newest} LIMIT ?`, [...ownParams, window]);
-            const ownKept = ownWindow.filter(keep);
-            if (ownKept.length >= needed || ownWindow.length < window)
-                return ownKept;
-        }
     }
-    // Text order is chronological only for standard UTC ISO (memory.ts), and a window of junk can hide older rows.
-    return run(`${ownWhere} ${newest}`, ownParams).filter(keep);
+    return [...kept, ...keptPastWindow(run, own, read, needed - kept.length, keep)];
+}
+// A window of refused rows can hide older ones, so read on in keyset pages, each four times the last, until enough are kept.
+function keptPastWindow(run, own, read, wanted, keep) {
+    const out = [];
+    let last = read[read.length - 1];
+    for (let size = read.length * 4; out.length < wanted; size *= 4) {
+        const page = run(`${own.where} AND created <= ? AND (created < ? OR id < ?) ${NEWEST} LIMIT ?`, [...own.params, last.created, last.created, last.id, size]);
+        out.push(...page.filter(keep));
+        if (page.length < size)
+            break;
+        last = page[page.length - 1];
+    }
+    return out;
 }
 // The pins plus the `recentNeeded` newest rows that pass `admit`, for ambient injection. One connection;
 // `recall` piggybacks the prompt-recall FTS query on it too. `origins` narrows the recent rows past the first window.
@@ -47,8 +60,7 @@ export function loadAmbientCandidates(hippoRoot, tenantId, recentNeeded, admit,
     // A SQL LIMIT takes an integer; the Array.slice this replaced truncated one,
     // and include_recent is any non-negative finite number at the HTTP edge.
     const needed = Math.trunc(recentNeeded);
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // SAFETY: every `where` below starts from MEMORY_SELECT_COLUMNS' table.
         const run = (where, params) => db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE ${where}`).all(...params).map(rowToEntry);
         const byId = new Map();
@@ -74,10 +86,7 @@ export function loadAmbientCandidates(hippoRoot, tenantId, recentNeeded, admit,
             ? loadRecallSearchEntriesFromDb(db, ftsQuery, { limit: recall.limit, tenantId, includeSuperseded: false, ownScope: recall.ownScope })
             : [];
         return { entries, recall: recallEntries };
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 // calculateStrength's decay exponent with its reward factor, pins first: the strongest rows, without scoring each one in JS.
 const DECAY_RANK_SQL = `pinned DESC,
@@ -102,70 +111,62 @@ export function loadContextCandidates(hippoRoot, tenantId, filter) {
         where.push(`(origin_project = '' OR ${originInSql(filter.project)})`);
         params.push(...filter.project);
     }
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // SAFETY: the outer SELECT names exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set; the rank sort carries ids only.
         const rows = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id IN (
         SELECT id FROM memories WHERE ${where.join(' AND ')} ORDER BY ${DECAY_RANK_SQL} LIMIT ?
       ) ORDER BY created ASC, id ASC`).all(...params, filter.now.toISOString(), Math.max(0, Math.trunc(filter.cap)));
         return rows.map(rowToEntry);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 // No owner: for session capture, a personal or connector-private row must never stop a team copy being written.
 const TEAM_VISIBLE = scopeAdmitSql('');
 /** Admits every scope, for a reader that sees the whole store, such as the CLI on its own machine. */
 export const EVERY_SCOPE = Object.freeze({ sql: '1', params: [] });
-/** Text, source and origin of tenant rows holding any of `words` that `admit` passes, by default the team-visible ones; a row equal to a text apart from spacing holds its every word.
- *  With `project`, only rows carrying one of those names and user-global rows, as loadContextCandidates' filter. No `tenantId` reads every tenant. */
+/** Tenant rows holding any of `words` that `admit` passes (default: team-visible); a row equal to a text apart from spacing holds its every word.
+ * With `project`, only rows carrying one of those names plus user-global rows, as loadContextCandidates' filter. No `tenantId` reads every tenant. */
 export function loadTextsHoldingWords(hippoRoot, tenantId, words, project, admit = TEAM_VISIBLE) {
     const unique = [...new Set(words)];
     const out = [];
     const tenantWhere = tenantId === undefined ? '1' : 'tenant_id = ?';
     const tenantParams = tenantId === undefined ? [] : [tenantId];
     const originWhere = project === undefined ? '' : ` AND (origin_project = '' OR ${originInSql(project)})`;
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // Chunked so one statement stays far under SQLite's bound-parameter limit.
         for (let i = 0; i < unique.length; i += 200) {
             const chunk = unique.slice(i, i + 200);
             // SAFETY: rows' shape matches the three columns named in the SELECT below.
-            const rows = db.prepare(`SELECT content, source, origin_project FROM memories WHERE ${tenantWhere}${originWhere} AND ${admit.sql} AND (${chunk.map(() => 'instr(content, ?) > 0').join(' OR ')})`).all(...tenantParams, ...(project ?? []), ...admit.params, ...chunk);
+            const rows = db.prepare(`SELECT content, source, origin_project FROM memories WHERE ${tenantWhere}${originWhere} AND ${admit.sql} AND (${chunk.map(() => 'instr(content, ?) ' +
+                '> 0').join(' OR ')})`).all(...tenantParams, ...(project ?? []), ...admit.params, ...chunk);
             for (const row of rows)
                 out.push({ content: row.content, source: row.source ?? 'cli', origin_project: row.origin_project });
         }
         return out;
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 /** A tenant's `limit` newest rows, oldest first: the tail of loadAllEntries' order, without reading the rows before it. */
 export function loadNewestEntries(hippoRoot, tenantId, limit) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // SAFETY: the SELECT names exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
         const rows = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE tenant_id = ? ORDER BY created DESC, id DESC LIMIT ?`).all(tenantId, limit);
         return rows.reverse().map(rowToEntry);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 function* contentsOf(rows) {
     for (const row of rows)
         yield row.content;
 }
-/** computeSchemaFit against every row of a tenant: tag counts come from one aggregate and texts stream one column, so no row is loaded. */
+/** How many of a tenant's newest rows schemaFitInStore reads; older rows no longer move the fit. */
+const SCHEMA_FIT_WINDOW_ROWS = 2000;
+/** computeSchemaFit against a tenant's newest SCHEMA_FIT_WINDOW_ROWS rows: tag counts come from one aggregate
+ * and texts stream one column, so no row is loaded. */
 export function schemaFitInStore(hippoRoot, tenantId, content, tags) {
-    const db = openStore(hippoRoot);
-    try {
+    const newest = 'SELECT tags_json, content FROM memories WHERE tenant_id = ? ORDER BY created DESC, id DESC LIMIT ?';
+    return onHandle(hippoRoot, (db) => {
         // One read transaction, so the row count and the texts come from the same snapshot.
         return withReadSnapshot(db, () => {
             // SAFETY: rows' shape matches the two columns named in the SELECT.
-            const groups = db.prepare('SELECT tags_json, COUNT(*) AS n FROM memories WHERE tenant_id = ? GROUP BY tags_json').all(tenantId);
+            const groups = db.prepare(`SELECT tags_json, COUNT(*) AS n FROM (${newest}) GROUP BY tags_json`).all(tenantId, SCHEMA_FIT_WINDOW_ROWS);
             let rows = 0;
             const tagCounts = new Map();
             for (const group of groups) {
@@ -173,28 +174,23 @@ export function schemaFitInStore(hippoRoot, tenantId, content, tags) {
                 for (const tag of parseJsonArray(group.tags_json))
                     tagCounts.set(tag, (tagCounts.get(tag) ?? 0) + group.n);
             }
-            // SHORTCUT: the text walk visits rows until a tenth of the tenant matches; a stored token count per tenant is the upgrade.
+            // SHORTCUT: only the newest SCHEMA_FIT_WINDOW_ROWS rows count, so older tags drop out;
+            // a stored per-tenant tag and token tally is the upgrade.
             // SAFETY: the SELECT names exactly the one column read.
-            const texts = db.prepare('SELECT content FROM memories WHERE tenant_id = ?').iterate(tenantId);
+            const texts = db.prepare(`SELECT content FROM (${newest})`)
+                .iterate(tenantId, SCHEMA_FIT_WINDOW_ROWS);
             return schemaFitFrom(content, tags, { rows, tagCounts, contents: contentsOf(texts) });
         });
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 /** Row count and newest `created` per source, for peer listings that need no row; all tenants when `tenantId` is absent. */
 export function tallySources(hippoRoot, tenantId) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const where = tenantId !== undefined ? 'WHERE tenant_id = ?' : '';
         // SAFETY: rows' shape matches the four aliased columns in the SELECT below.
         return db.prepare(`SELECT COALESCE(source, 'cli') AS source, COUNT(*) AS count, MAX(created) AS latest, MIN(created || char(31) || id) AS first
        FROM memories ${where} GROUP BY COALESCE(source, 'cli')`).all(...(tenantId !== undefined ? [tenantId] : []));
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 // A malformed or non-array JSON list reads as empty, as parseJsonArray does, instead of failing json_each.
 export const jsonList = (column) => `(CASE WHEN json_valid(${column}) AND json_type(${column}) = 'array' THEN ${column} ELSE '[]' END)`;
@@ -202,8 +198,7 @@ export const jsonList = (column) => `(CASE WHEN json_valid(${column}) AND json_t
 export function loadStrengthTallies(hippoRoot, tenantId, now, atRiskBelow) {
     // An unparseable date scores NULL in SQL and 0 in calculateStrength.
     const strength = `COALESCE(${strengthSql(now)}, 0)`;
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         // SAFETY: one aggregate row whose columns are the aliases named below.
         const row = db.prepare(`SELECT
       COUNT(*) AS total,
@@ -219,9 +214,62 @@ export function loadStrengthTallies(hippoRoot, tenantId, now, atRiskBelow) {
             strengthSum: Number(row.strengthSum),
             atRisk: Number(row.atRisk),
         };
+    }, openStore);
+}
+// What calculateStrength and facetsOf read, plus the layer: no text and no JSON column.
+const STATUS_ROW_COLUMNS = [
+    'layer', 'confidence', 'pinned', 'created', 'last_retrieved', 'half_life_days', 'retrieval_count',
+    'emotional_valence', 'outcome_positive', 'outcome_negative',
+];
+// Scored in JavaScript, not with strengthSql: SQLite reads fewer date shapes than Date does, so its counts would differ.
+function tallyStatusRows(rows, now, atRiskBelow) {
+    const byLayer = { [Layer.Buffer]: 0, [Layer.Episodic]: 0, [Layer.Semantic]: 0, [Layer.Trace]: 0 };
+    const byConfidence = { verified: 0, observed: 0, inferred: 0, stale: 0 };
+    const sums = { total: 0, strength: 0, pinned: 0, atRisk: 0, agedOut: 0 };
+    for (const row of rows) {
+        // rowToEntry's defaults for these columns, so a row scores as its loaded entry would.
+        const entry = {
+            pinned: Boolean(row.pinned),
+            confidence: row.confidence ?? 'observed',
+            created: row.created,
+            last_retrieved: row.last_retrieved,
+            half_life_days: Number(row.half_life_days ?? FALLBACK_HALF_LIFE_DAYS),
+            retrieval_count: Number(row.retrieval_count ?? 0),
+            emotional_valence: row.emotional_valence ?? 'neutral',
+            outcome_positive: Number(row.outcome_positive ?? 0),
+            outcome_negative: Number(row.outcome_negative ?? 0),
+        };
+        const strength = calculateStrength(entry, now);
+        const facets = facetsOf(entry, now);
+        sums.total++;
+        sums.strength += strength;
+        byLayer[row.layer] = (byLayer[row.layer] ?? 0) + 1;
+        byConfidence[facets.tier] = (byConfidence[facets.tier] ?? 0) + 1;
+        if (entry.pinned)
+            sums.pinned++;
+        if (strength < atRiskBelow)
+            sums.atRisk++;
+        if (facets.agedOut)
+            sums.agedOut++;
     }
-    finally {
-        closeHippoDb(db);
-    }
+    const { total, pinned, atRisk, agedOut } = sums;
+    return { total, byLayer, byConfidence, pinned, atRisk, agedOut, avgStrength: total > 0 ? sums.strength / total : 0 };
+}
+/** The counts `hippo status` prints, from one pass over ten narrow columns: no text is read and no row array is built. */
+export function loadStatusCounts(hippoRoot, now, atRiskBelow) {
+    return onHandle(hippoRoot, (db) => {
+        // One read transaction, so the row tallies and the two counts describe the same store.
+        return withReadSnapshot(db, () => {
+            // loadAllEntries' order, so the strengths add up in the order they did and the average rounds the same.
+            // SAFETY: the SELECT names exactly StatusRow's columns, and the store writes `layer` only from the Layer enum.
+            const rows = db.prepare(`SELECT ${STATUS_ROW_COLUMNS.join(', ')} FROM memories ORDER BY created ASC, id ASC`).iterate();
+            const tallies = tallyStatusRows(rows, now, atRiskBelow);
+            // SAFETY: one row whose columns are the two aliases named below.
+            const counts = db.prepare(`SELECT
+        (SELECT COUNT(*) FROM memory_conflicts WHERE status = 'open') AS openConflicts,
+        (SELECT COUNT(*) FROM memory_vectors WHERE memory_id IN (SELECT id FROM memories)) AS embedded`).get();
+            return { ...tallies, openConflicts: Number(counts.openConflicts), embedded: Number(counts.embedded) };
+        });
+    }, openStore);
 }
 //# sourceMappingURL=candidates.js.map

package/dist/store/capture-write.d.ts

@@ -0,0 +1,17 @@
+import type { MemoryEntry } from '../core/memory.js';
+export type CapturedOutcome = 'captured' | 'skipped' | 'rejected';
+export interface CaptureItem {
+    readonly content: string;
+    /** Built only for an item that is not a repeat of an earlier one, since building can throw. */
+    readonly makeEntry: () => MemoryEntry;
+}
+export interface CaptureWriteOpts {
+    readonly actor?: string;
+    /** No stats, as in a server process. */
+    readonly lean: boolean;
+    /** Called with each captured entry after its write, so the caller can embed it; the store never picks a provider. */
+    readonly onCaptured?: (entry: MemoryEntry) => void;
+}
+/** One outcome per item, in order. `keys` holds the texts already stored and gains each one written, so a repeat inside the batch is skipped. */
+export declare function writeCapturedItems(hippoRoot: string, items: readonly CaptureItem[], keys: Set<string>, opts: CaptureWriteOpts): CapturedOutcome[];
+//# sourceMappingURL=capture-write.d.ts.map