hippo-memory 1.68.0 → 1.70.0

package/dist/{token-ledger.js → store/token-ledger.js}

@@ -23,9 +23,12 @@
  * transcript file. Writes are best-effort at the call sites; a ledger failure
  * must never break recall.
  */
-import { createHash } from 'node:crypto';
 import { open } from 'node:fs/promises';
-import { isJsonString } from './json.js';
+import { withWriteScope } from '../db/index.js';
+import { isJsonString, isJsonObjectLiteral } from '../util/json.js';
+import { DAY_MS } from '../util/time.js';
+import { countSkipsAfter, deleteRereadRows, injectedBlocks, insertTokenRow, latestInjectOrReset, pruneTokenRowsBefore, sessionTokenRows, sessionTotals, surfaceTotals, } from './token-ledger-rows.js';
+import { DATE_PREFIX_CHARS } from '../util/token-text.js';
 /** All surfaces, in report order. */
 export const TOKEN_SURFACES = [
     'hook', 'hook_recall', 'compact_resume', 'context', 'recall', 'mcp_recall', 'mcp_context',
@@ -35,26 +38,23 @@ export const TOKEN_SURFACES = [
 export const REREAD_SURFACES = ['hook', 'hook_recall', 'compact_resume'];
 /** Rows older than this are pruned on write. */
 export const TOKEN_LEDGER_RETENTION_DAYS = 90;
-/**
- * Rough token estimate: characters / 4. The single estimate behind every
- * token budget and ledger count in hippo.
- */
-export function estimateTokens(text) {
-    return Math.ceil(text.length / 4);
-}
-/** Stable 16-hex-char hash of a rendered block, for change detection. */
-export function blockHash(text) {
-    return createHash('sha256').update(text).digest('hex').slice(0, 16);
-}
 /**
  * Append one ledger row and prune rows past {@link TOKEN_LEDGER_RETENTION_DAYS}.
  */
 export function recordTokenUse(db, use) {
     const now = use.now ?? new Date().toISOString();
-    db.prepare(`INSERT INTO token_ledger (ts, tenant_id, session_id, surface, event, items, tokens, block_hash)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(now, use.tenantId, use.sessionId ?? null, use.surface, use.event, Math.max(0, Math.round(use.items)), Math.max(0, Math.round(use.tokens)), use.hash ?? null);
-    const cutoff = new Date(Date.parse(now) - TOKEN_LEDGER_RETENTION_DAYS * 86_400_000).toISOString();
-    db.prepare(`DELETE FROM token_ledger WHERE ts < ?`).run(cutoff);
+    insertTokenRow(db, {
+        ts: now,
+        tenantId: use.tenantId,
+        sessionId: use.sessionId ?? null,
+        surface: use.surface,
+        event: use.event,
+        items: Math.max(0, Math.round(use.items)),
+        tokens: Math.max(0, Math.round(use.tokens)),
+        blockHash: use.hash ?? null,
+    });
+    const cutoff = new Date(Date.parse(now) - TOKEN_LEDGER_RETENTION_DAYS * DAY_MS).toISOString();
+    pruneTokenRowsBefore(db, cutoff);
 }
 /**
  * The last block this session injected on `surface`, or null when the
@@ -64,15 +64,10 @@ export function recordTokenUse(db, use) {
 export function lastSentState(db, tenantId, sessionId, surface) {
     if (!sessionId)
         return null;
-    // SAFETY: the SELECT names exactly these three columns.
-    const anchor = db.prepare(`SELECT id, event, block_hash FROM token_ledger
-     WHERE tenant_id = ? AND session_id = ? AND surface = ? AND event IN ('inject', 'reset')
-     ORDER BY id DESC LIMIT 1`).get(tenantId, sessionId, surface);
+    const anchor = latestInjectOrReset(db, tenantId, sessionId, surface);
     if (!anchor || anchor.event === 'reset' || !anchor.block_hash)
         return null;
-    // SAFETY: the SELECT names exactly this one aggregate column.
-    const skips = db.prepare(`SELECT COUNT(*) AS n FROM token_ledger
-     WHERE tenant_id = ? AND session_id = ? AND surface = ? AND event = 'skip' AND id > ?`).get(tenantId, sessionId, surface, anchor.id);
+    const skips = countSkipsAfter(db, tenantId, sessionId, surface, anchor.id);
     return { hash: anchor.block_hash, skipsSince: Number(skips?.n ?? 0) };
 }
 /**
@@ -93,17 +88,7 @@ export function shouldSkipUnchanged(last, hash, refreshTurns) {
  * omitted.
  */
 export function summarizeTokenUse(db, tenantId, sinceIso) {
-    // SAFETY: the SELECT names exactly these columns, all aggregates or TEXT.
-    const rows = db.prepare(`SELECT surface,
-            SUM(CASE WHEN event = 'inject' THEN 1 ELSE 0 END) AS injected,
-            SUM(CASE WHEN event = 'inject' THEN tokens ELSE 0 END) AS tokens,
-            SUM(CASE WHEN event = 'skip' THEN 1 ELSE 0 END) AS skipped,
-            SUM(CASE WHEN event = 'skip' THEN tokens ELSE 0 END) AS avoided,
-            SUM(CASE WHEN event = 'reread' THEN tokens ELSE 0 END) AS reread,
-            COUNT(DISTINCT session_id) AS sessions
-     FROM token_ledger
-     WHERE tenant_id = ? AND ts >= ?
-     GROUP BY surface`).all(tenantId, sinceIso);
+    const rows = surfaceTotals(db, tenantId, sinceIso);
     const bySurface = new Map(rows.map((r) => [r.surface, r]));
     const surfaces = [];
     for (const surface of TOKEN_SURFACES) {
@@ -120,13 +105,7 @@ export function summarizeTokenUse(db, tenantId, sinceIso) {
             sessions: Number(r.sessions),
         });
     }
-    // SAFETY: the SELECT names exactly these four aggregate columns.
-    const perSession = db.prepare(`SELECT COUNT(DISTINCT session_id) AS sessions,
-            COUNT(DISTINCT CASE WHEN event <> 'reset' AND surface IN (${REREAD_SURFACES.map(() => '?').join(', ')}) THEN session_id END) AS hook_sessions,
-            COUNT(DISTINCT CASE WHEN event = 'reread' THEN session_id END) AS reread_sessions,
-            SUM(CASE WHEN event = 'inject' THEN tokens ELSE 0 END) AS tokens
-     FROM token_ledger
-     WHERE tenant_id = ? AND ts >= ? AND session_id IS NOT NULL AND event <> 'arm'`).get(...REREAD_SURFACES, tenantId, sinceIso);
+    const perSession = sessionTotals(db, tenantId, sinceIso, REREAD_SURFACES);
     const sessionCount = Number(perSession?.sessions ?? 0);
     const sessionTokens = Number(perSession?.tokens ?? 0);
     return {
@@ -145,10 +124,6 @@ export function summarizeTokenUse(db, tenantId, sinceIso) {
 export function isSyntheticMessage(message) {
     return message.model === '<synthetic>';
 }
-/** JSON-value plain-object check (excludes arrays and null). */
-function isJsonObject(value) {
-    return value !== undefined && value !== null && !Array.isArray(value) && value.constructor === Object;
-}
 /** A Claude Code hook payload on stdin as a JSON object; null when empty, malformed or not an object. */
 function parseHookPayload(stdinText) {
     if (!stdinText || stdinText.trim() === '')
@@ -156,7 +131,7 @@ function parseHookPayload(stdinText) {
     try {
         // SAFETY: JSON.parse returns a JSON value by definition.
         const payload = JSON.parse(stdinText.trim());
-        return isJsonObject(payload) ? payload : null;
+        return isJsonObjectLiteral(payload) ? payload : null;
     }
     catch {
         // Malformed is one of the null cases the docblock names.
@@ -190,15 +165,7 @@ export function isSubagentPayload(stdinText) {
  * transcript file name, so these join to the host's own usage records.
  */
 export function tokensBySession(db, tenantId, sinceIso) {
-    // SAFETY: the SELECT names exactly these columns, all aggregates or TEXT.
-    const rows = db.prepare(`SELECT session_id,
-            SUM(CASE WHEN event = 'inject' THEN tokens ELSE 0 END) AS sent,
-            SUM(CASE WHEN event = 'skip' THEN tokens ELSE 0 END) AS skipped,
-            SUM(CASE WHEN event = 'inject' THEN 1 ELSE 0 END) AS injections
-     FROM token_ledger
-     WHERE tenant_id = ? AND ts >= ? AND session_id IS NOT NULL AND event <> 'arm'
-     GROUP BY session_id`).all(tenantId, sinceIso);
-    return rows.map((r) => ({
+    return sessionTokenRows(db, tenantId, sinceIso).map((r) => ({
         sessionId: r.session_id,
         sent: Number(r.sent),
         skipped: Number(r.skipped),
@@ -227,7 +194,7 @@ export async function readApiCalls(transcriptPath) {
                 continue;
             }
             // Sidechain calls, sidechain compactions and `<synthetic>` messages never touch the main context.
-            if (!isJsonObject(entry) || entry.isSidechain === true)
+            if (!isJsonObjectLiteral(entry) || entry.isSidechain === true)
                 continue;
             if (entry.subtype === 'compact_boundary') {
                 compactions += 1;
@@ -235,9 +202,9 @@ export async function readApiCalls(transcriptPath) {
             }
             // One call spans lines sharing a message id.
             const message = entry.message;
-            if (entry.type !== 'assistant' || !isJsonObject(message))
+            if (entry.type !== 'assistant' || !isJsonObjectLiteral(message))
                 continue;
-            if (!isJsonObject(message.usage) || isSyntheticMessage(message) || !isJsonString(message.id))
+            if (!isJsonObjectLiteral(message.usage) || isSyntheticMessage(message) || !isJsonString(message.id))
                 continue;
             if (seen.has(message.id))
                 continue;
@@ -262,15 +229,11 @@ export function carryingCalls(calls, at) {
 }
 /** Replace a session's `reread` rows in one transaction, one per {@link REREAD_SURFACES} surface and UTC day; returns the tokens booked. */
 export function recordRereads(db, tenantId, sessionId, calls) {
-    db.exec('BEGIN IMMEDIATE');
-    let committed = false;
-    try {
-        // SAFETY: the SELECT names exactly these three columns.
-        const rows = db.prepare(`SELECT ts, surface, tokens FROM token_ledger
-       WHERE tenant_id = ? AND session_id = ? AND event = 'inject' AND surface IN (${REREAD_SURFACES.map(() => '?').join(', ')})`).all(tenantId, sessionId, ...REREAD_SURFACES);
+    return withWriteScope(db, 'record_rereads', () => {
+        const rows = injectedBlocks(db, tenantId, sessionId, REREAD_SURFACES);
         const days = new Map();
         const add = (surface, at, rereads, tokens) => {
-            const key = `${surface} ${new Date(at).toISOString().slice(0, 10)}`;
+            const key = `${surface} ${new Date(at).toISOString().slice(0, DATE_PREFIX_CHARS)}`;
             const day = days.get(key) ?? { surface, at, rereads: 0, tokens: 0 };
             days.set(key, { surface, at: Math.max(day.at, at), rereads: day.rereads + rereads, tokens: day.tokens + tokens });
         };
@@ -282,23 +245,13 @@ export function recordRereads(db, tenantId, sessionId, calls) {
             for (const call of carryingCalls(calls, sentAt).slice(1))
                 add(row.surface, call.at, 1, Number(row.tokens));
         }
-        db.prepare(`DELETE FROM token_ledger WHERE tenant_id = ? AND session_id = ? AND event = 'reread'`).run(tenantId, sessionId);
+        deleteRereadRows(db, tenantId, sessionId);
         for (const day of days.values()) {
             recordTokenUse(db, {
                 tenantId, sessionId, surface: day.surface, event: 'reread', items: day.rereads, tokens: day.tokens, now: new Date(day.at).toISOString(),
             });
         }
-        db.exec('COMMIT');
-        committed = true;
         return [...days.values()].reduce((sum, day) => sum + day.tokens, 0);
-    }
-    finally {
-        if (!committed) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* preserve the original throw */ }
-        }
-    }
+    });
 }
 //# sourceMappingURL=token-ledger.js.map

package/dist/store/tombstone-checks.d.ts

@@ -0,0 +1,12 @@
+import { type AppendAuditOpts } from './audit.js';
+import { type RejectedValueRow } from './rejection.js';
+/** Tombstone lookups and their refusal audit rows on one handle: opened on first use, never under dryRun, closed once. */
+export interface TombstoneChecks {
+    /** The tenant's tombstone for `digest`; null when there is none, and always under dryRun. */
+    find(tenantId: string, digest: string): RejectedValueRow | null;
+    /** One audit row on the same handle; nothing under dryRun. */
+    audit(event: AppendAuditOpts): void;
+    close(): void;
+}
+export declare function lazyTombstoneChecks(hippoRoot: string, dryRun: boolean): TombstoneChecks;
+//# sourceMappingURL=tombstone-checks.d.ts.map

package/dist/store/tombstone-checks.js

@@ -0,0 +1,31 @@
+// Sleep's tombstone checks run on one handle for the whole pass, owned here so no stage holds a raw one.
+import { closeHippoDb, openHippoDb } from '../db/index.js';
+import { appendAuditEvent } from './audit.js';
+import { findRejectedValue } from './rejection.js';
+// Lazy so a sleep that checks nothing never opens the store; make it IMMEDIATELY before the try whose
+// finally closes it, so a throw in any phase cannot leak the handle.
+export function lazyTombstoneChecks(hippoRoot, dryRun) {
+    let handle = null;
+    const opened = () => {
+        if (dryRun)
+            return null;
+        handle ??= openHippoDb(hippoRoot);
+        return handle;
+    };
+    return {
+        find(tenantId, digest) {
+            const db = opened();
+            return db ? findRejectedValue(db, tenantId, digest) : null;
+        },
+        audit(event) {
+            const db = opened();
+            if (db)
+                appendAuditEvent(db, event);
+        },
+        close() {
+            if (handle)
+                closeHippoDb(handle);
+        },
+    };
+}
+//# sourceMappingURL=tombstone-checks.js.map

package/dist/store/usage-reports.d.ts

@@ -0,0 +1,7 @@
+import { type TokenSummary } from './token-ledger.js';
+import { type FailureSummary } from './failure-log.js';
+/** One tenant's token ledger totals since `sinceIso`. */
+export declare function tokenUseSummary(hippoRoot: string, tenantId: string, sinceIso: string): TokenSummary;
+/** One tenant's failure log totals since `sinceIso`. */
+export declare function failureLogSummary(hippoRoot: string, tenantId: string, sinceIso: string): FailureSummary;
+//# sourceMappingURL=usage-reports.d.ts.map

package/dist/store/usage-reports.js

@@ -0,0 +1,26 @@
+// The token-use and failure reports, each read on one handle of its own.
+// A file apart from token-ledger-rows.ts: src/store/token-ledger.ts imports that one, so a summary there would be an import cycle.
+import { closeHippoDb, openHippoDb } from '../db/index.js';
+import { summarizeTokenUse } from './token-ledger.js';
+import { summarizeFailures } from './failure-log.js';
+/** One tenant's token ledger totals since `sinceIso`. */
+export function tokenUseSummary(hippoRoot, tenantId, sinceIso) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        return summarizeTokenUse(db, tenantId, sinceIso);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** One tenant's failure log totals since `sinceIso`. */
+export function failureLogSummary(hippoRoot, tenantId, sinceIso) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        return summarizeFailures(db, tenantId, sinceIso);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=usage-reports.js.map

package/dist/store/vector-writes.d.ts

@@ -1,6 +1,13 @@
-import { type DatabaseSyncLike } from '../db.js';
-import type { MemoryEntry } from '../memory.js';
-import type { VectorBackfillQuery, VectorWrite, VectorWriteResult } from '../store-port.js';
+import { type DatabaseSyncLike } from '../db/index.js';
+import type { MemoryEntry } from '../core/memory.js';
+import type { PhysicsParticle } from '../core/physics.js';
+import type { VectorBackfillQuery, VectorWrite, VectorWriteResult } from './port.js';
 export declare function entriesWithoutVectorAt(db: DatabaseSyncLike, query: VectorBackfillQuery): MemoryEntry[];
 export declare function writeVectorsAt(db: DatabaseSyncLike, write: VectorWrite): VectorWriteResult;
+/** Every particle stored under `hippoRoot`. */
+export declare function loadStoredParticles(hippoRoot: string): PhysicsParticle[];
+/** Writes `particles` over their stored state under `hippoRoot`, as one batch. */
+export declare function saveStoredParticles(hippoRoot: string, particles: PhysicsParticle[]): void;
+/** Replaces every particle under `hippoRoot` with a fresh one per entry that has an embedding; returns how many. */
+export declare function resetStoredParticles(hippoRoot: string, entries: MemoryEntry[], embeddingIndex: Record<string, number[]>): number;
 //# sourceMappingURL=vector-writes.d.ts.map

package/dist/store/vector-writes.js

@@ -1,8 +1,8 @@
 // hippo.db's half of the VectorWrites store group.
-import { setMeta, withWriteScope } from '../db.js';
-import { embeddingIndexStateOn, replacesIndex } from '../embeddings.js';
-import { float32ToBuffer } from '../physics-state.js';
-import { EMBEDDING_MODEL_META_KEY, upsertVectors } from '../vector-store.js';
+import { closeHippoDb, openHippoDb, setMeta, withWriteScope } from '../db/index.js';
+import { embeddingIndexStateOn, replacesIndex } from './embeddings/index.js';
+import { float32ToBuffer, loadPhysicsState, resetAllPhysicsState, savePhysicsState } from '../db/physics-state.js';
+import { EMBEDDING_MODEL_META_KEY, upsertVectors } from '../db/vector-store.js';
 import { chunked } from './entry-reads.js';
 import { MEMORY_SELECT_COLUMNS, rowToEntry } from './rows.js';
 const MAX_BACKFILL_PAGE = 500;
@@ -22,7 +22,7 @@ function ownedIds(db, ids, tenantId) {
     const owned = new Set();
     for (const chunk of chunked([...new Set(ids)])) {
         // SAFETY: the SELECT names one column, id.
-        const rows = db.prepare(`SELECT id FROM memories WHERE tenant_id = ? AND id IN (${chunk.map(() => '?').join(', ')})`).all(tenantId, ...chunk);
+        const rows = db.prepare(`SELECT id FROM memories WHERE +tenant_id = ? AND id IN (${chunk.map(() => '?').join(', ')})`).all(tenantId, ...chunk);
         for (const row of rows)
             owned.add(row.id);
     }
@@ -56,4 +56,34 @@ export function writeVectorsAt(db, write) {
         return { written, modelMismatch: false };
     });
 }
+/** Every particle stored under `hippoRoot`. */
+export function loadStoredParticles(hippoRoot) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        return Array.from(loadPhysicsState(db).values());
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Writes `particles` over their stored state under `hippoRoot`, as one batch. */
+export function saveStoredParticles(hippoRoot, particles) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        savePhysicsState(db, particles);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Replaces every particle under `hippoRoot` with a fresh one per entry that has an embedding; returns how many. */
+export function resetStoredParticles(hippoRoot, entries, embeddingIndex) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        return resetAllPhysicsState(db, entries, embeddingIndex);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 //# sourceMappingURL=vector-writes.js.map

package/dist/{working-memory.d.ts → store/working-memory.d.ts}

@@ -5,7 +5,7 @@
  * importance-ranked, and automatically evicted when the buffer
  * exceeds WM_MAX_ENTRIES per scope.
  */
-import type { JsonValue } from './json.js';
+import type { JsonValue } from '../util/json.js';
 export declare const WM_MAX_ENTRIES = 20;
 export type JsonObject = {
     [key: string]: JsonValue;
@@ -34,6 +34,7 @@ export declare function wmPush(hippoRoot: string, opts: {
     sessionId?: string;
     taskId?: string;
     metadata?: JsonObject;
+    tenantId?: string;
 }): number;
 /**
  * Read working memory entries, sorted by importance DESC.
@@ -42,6 +43,7 @@ export declare function wmRead(hippoRoot: string, opts?: {
     scope?: string;
     sessionId?: string;
     limit?: number;
+    tenantId?: string;
 }): WorkingMemoryItem[];
 /**
  * Clear (delete) working memory entries. Returns the count deleted.
@@ -49,6 +51,7 @@ export declare function wmRead(hippoRoot: string, opts?: {
 export declare function wmClear(hippoRoot: string, opts?: {
     scope?: string;
     sessionId?: string;
+    tenantId?: string;
 }): number;
 /**
  * Flush working memory — delete entries after session end.
@@ -59,5 +62,6 @@ export declare function wmClear(hippoRoot: string, opts?: {
 export declare function wmFlush(hippoRoot: string, opts?: {
     scope?: string;
     sessionId?: string;
+    tenantId?: string;
 }): number;
 //# sourceMappingURL=working-memory.d.ts.map

package/dist/{working-memory.js → store/working-memory.js}

@@ -5,8 +5,10 @@
  * importance-ranked, and automatically evicted when the buffer
  * exceeds WM_MAX_ENTRIES per scope.
  */
-import { closeHippoDb } from './db.js';
-import { openStore } from './store/open.js';
+import { closeHippoDb, withWriteScope } from '../db/index.js';
+import { openStore } from './open.js';
+import { warnDamagedColumn } from '../util/stored-json.js';
+import { resolveTenantId } from './tenant.js';
 export const WM_MAX_ENTRIES = 20;
 function rowToItem(row) {
     let metadata = {};
@@ -17,7 +19,8 @@ function rowToItem(row) {
         metadata = JSON.parse(row.metadata_json);
     }
     catch {
-        // malformed JSON — default to empty
+        // The item still lists with its content; only its metadata reads as empty.
+        warnDamagedColumn({ table: 'working_memory', id: row.id, column: 'metadata_json' }, 'not valid JSON');
     }
     return {
         id: row.id,
@@ -42,56 +45,51 @@ export function wmPush(hippoRoot, opts) {
     try {
         const now = new Date().toISOString();
         const importance = opts.importance ?? 0;
-        db.exec('BEGIN IMMEDIATE');
-        try {
+        const tenantId = opts.tenantId ?? resolveTenantId({});
+        return withWriteScope(db, 'wm_push', () => {
             const result = db.prepare(`
-        INSERT INTO working_memory(scope, session_id, task_id, importance, content, metadata_json, created_at, updated_at)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-      `).run(opts.scope, opts.sessionId ?? null, opts.taskId ?? null, importance, opts.content, JSON.stringify(opts.metadata ?? {}), now, now);
+        INSERT INTO working_memory(scope, session_id, task_id, importance, content, metadata_json, created_at, updated_at, tenant_id)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(opts.scope, opts.sessionId ?? null, opts.taskId ?? null, importance, opts.content, JSON.stringify(opts.metadata ?? {}), now, now, tenantId);
             const id = Number(result.lastInsertRowid ?? 0);
-            // Evict if over capacity for this scope
-            // SAFETY: `COUNT(*) AS cnt` on a scoped query always returns exactly
-            // one row shaped { cnt }; .get() returns undefined only if the driver
-            // yields no row, which COUNT(*) never does.
-            const countRow = db.prepare(`
-        SELECT COUNT(*) AS cnt FROM working_memory WHERE scope = ?
-      `).get(opts.scope);
-            const count = Number(countRow?.cnt ?? 0);
-            if (count > WM_MAX_ENTRIES) {
-                const excess = count - WM_MAX_ENTRIES;
-                db.prepare(`
-          DELETE FROM working_memory
-          WHERE id IN (
-            SELECT id FROM working_memory
-            WHERE scope = ?
-            ORDER BY importance ASC, created_at ASC
-            LIMIT ?
-          )
-        `).run(opts.scope, excess);
-            }
-            db.exec('COMMIT');
+            evictOverCapacity(db, opts.scope, tenantId);
             return id;
-        }
-        catch (error) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* ignore */ }
-            throw error;
-        }
+        });
     }
     finally {
         closeHippoDb(db);
     }
 }
+function evictOverCapacity(db, scope, tenantId) {
+    // Evict if over capacity for this scope
+    // SAFETY: `COUNT(*) AS cnt` on a scoped query always returns exactly
+    // one row shaped { cnt }; .get() returns undefined only if the driver
+    // yields no row, which COUNT(*) never does.
+    const countRow = db.prepare(`
+    SELECT COUNT(*) AS cnt FROM working_memory WHERE scope = ? AND tenant_id = ?
+  `).get(scope, tenantId);
+    const count = Number(countRow?.cnt ?? 0);
+    if (count > WM_MAX_ENTRIES) {
+        const excess = count - WM_MAX_ENTRIES;
+        db.prepare(`
+      DELETE FROM working_memory
+      WHERE id IN (
+        SELECT id FROM working_memory
+        WHERE scope = ? AND tenant_id = ?
+        ORDER BY importance ASC, created_at ASC
+        LIMIT ?
+      )
+    `).run(scope, tenantId, excess);
+    }
+}
 /**
  * Read working memory entries, sorted by importance DESC.
  */
 export function wmRead(hippoRoot, opts) {
     const db = openStore(hippoRoot);
     try {
-        const clauses = [];
-        const params = [];
+        const clauses = ['tenant_id = ?'];
+        const params = [opts?.tenantId ?? resolveTenantId({})];
         if (opts?.scope) {
             clauses.push('scope = ?');
             params.push(opts.scope);
@@ -124,8 +122,8 @@ export function wmRead(hippoRoot, opts) {
 export function wmClear(hippoRoot, opts) {
     const db = openStore(hippoRoot);
     try {
-        const clauses = [];
-        const params = [];
+        const clauses = ['tenant_id = ?'];
+        const params = [opts?.tenantId ?? resolveTenantId({})];
         if (opts?.scope) {
             clauses.push('scope = ?');
             params.push(opts.scope);

package/dist/support-bundle.d.ts

@@ -1,5 +1,5 @@
 import { type DoctorOpts } from './doctor.js';
-import type { JsonObject } from './working-memory.js';
+import type { JsonObject } from './store/working-memory.js';
 export interface SupportBundleOpts extends DoctorOpts {
     readonly cwd: string;
     readonly home: string;

package/dist/support-bundle.js

@@ -1,24 +1,26 @@
 /** `hippo support-bundle`: one redacted JSON snapshot for a support ticket. Read-only (SQLite may leave empty -wal and -shm files); never touches memory content. */
-import { envByName, processEnv } from './env.js';
+import { envByName, processEnv } from './util/env.js';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { pathToFileURL } from 'url';
-import { findHippoStoreDir, isGlobalStoreRoot, realpathOrResolve } from './project-identity.js';
-import { getGlobalRoot } from './shared.js';
+import { findHippoStoreDir, isGlobalStoreRoot } from './core/project-identity.js';
+import { realpathOrResolve } from './util/real-path.js';
+import { getGlobalRoot } from './sharing/shared.js';
 import { isInitialized } from './store/open.js';
-import { openHippoDbReadOnly, closeHippoDb, getSchemaVersion, getMeta, countTableRows } from './db.js';
+import { readStoreInventory } from './store/diagnostics.js';
 import { runDoctor } from './doctor.js';
-import { loadConfig } from './config.js';
-import { redactSecretsStrict } from './secret-detect.js';
-import { isJsonString } from './json.js';
-import { escapeRegex } from './escape.js';
+import { loadConfig } from './core/config.js';
+import { redactSecretsStrict } from './util/secret-detect.js';
+import { isJsonString, isJsonObject } from './util/json.js';
+import { escapeRegex } from './util/escape.js';
+import { errorMessage } from './util/log.js';
 const TAIL_MAX_BYTES = 256 * 1024;
 export const TAIL_MAX_LINES = 200;
 const TAIL_MAX_LINE_CHARS = 2000;
 // Greedy on purpose: complete key blocks are redacted first, so any END left is an orphan and what precedes it may be key body.
 const ORPHAN_KEY_END_RE = /^[\s\S]*-----END [A-Z ]*PRIVATE KEY-----/;
-// The other env vars hippo reads outside the HIPPO_ prefix (src/embedding-provider.ts, connectors/*).
+// The other env vars hippo reads outside the HIPPO_ prefix (src/store/embeddings/provider.ts, connectors/*).
 const OTHER_ENV_NAMES = [
     'ANTHROPIC_API_KEY', 'OPENAI_API_KEY', 'VOYAGE_API_KEY', 'COHERE_API_KEY', 'TYPESAFE_API_KEY',
     'GITHUB_TOKEN', 'GITHUB_WEBHOOK_SECRET', 'GITHUB_WEBHOOK_SECRET_PREVIOUS',
@@ -27,9 +29,6 @@ const OTHER_ENV_NAMES = [
     'XDG_DATA_HOME', 'MCP_SSE_HEARTBEAT_MS', 'MCP_SSE_MAX_AGE_SEC',
 ];
 const CONFIG_SECRET_KEY_RE = /key|token|secret|passw|credential|auth|cookie|bearer|signature|private/i;
-function isJsonObject(v) {
-    return typeof v === 'object' && v !== null && !Array.isArray(v);
-}
 function buildRuntime() {
     return {
         node: process.versions.node,
@@ -39,17 +38,6 @@ function buildRuntime() {
         osRelease: os.release(),
     };
 }
-function listTableNames(db) {
-    // SAFETY: each row's shape matches the single `name` column named in the SELECT above.
-    const rows = db.prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND sql NOT LIKE 'CREATE VIRTUAL TABLE%' ORDER BY name`).all();
-    return rows.map((r) => r.name);
-}
-function countTables(db) {
-    const tables = {};
-    for (const name of listTableNames(db))
-        tables[name] = countTableRows(db, name);
-    return tables;
-}
 function redactConfigValue(value) {
     if (Array.isArray(value))
         return value.map(redactConfigValue);
@@ -88,21 +76,13 @@ function buildStoreEntry(kind, storeDir) {
     const walPath = `${dbPath}-wal`;
     if (fs.existsSync(walPath))
         files['hippo.db-wal'] = fs.statSync(walPath).size;
-    let db = null;
     try {
-        db = openHippoDbReadOnly(storeDir);
-        const schemaVersion = getSchemaVersion(db);
-        const minCompatibleBinary = getMeta(db, 'min_compatible_binary', '') || null;
-        const tables = countTables(db);
+        const { schemaVersion, minCompatibleBinary, tables } = readStoreInventory(storeDir);
         const { configFile, config } = readStoreConfig(storeDir);
         return { kind, path: storeDir, schemaVersion, minCompatibleBinary, files, tables, configFile, config };
     }
     catch (err) {
-        return { kind, path: storeDir, error: err instanceof Error ? err.message : String(err) };
-    }
-    finally {
-        if (db !== null)
-            closeHippoDb(db);
+        return { kind, path: storeDir, error: errorMessage(err) };
     }
 }
 function buildStores(opts) {

package/dist/{gated-write.d.ts → trust/gated-write.d.ts}

@@ -1,5 +1,5 @@
-import type { DatabaseSyncLike } from './db.js';
-import type { MemoryEntry } from './memory.js';
+import type { DatabaseSyncLike } from '../db/index.js';
+import type { MemoryEntry } from '../core/memory.js';
 export type GatedWriteResult = 'written' | 'skipped:not-worth-storing' | 'skipped:secret' | 'skipped:rejected';
 /** Runs on the caller's handle so it nests in the caller's transaction (writeEntry would open a second handle and wait on that lock); the caller mirrors after commit with an entry it stamped itself. The rejection audit lands inside that transaction, which is safe because a batch that rolls back stays `summarised` and replay writes the audit again. */
 export declare function gatedWrite(db: DatabaseSyncLike, hippoRoot: string, entry: MemoryEntry, opts?: {

package/dist/{gated-write.js → trust/gated-write.js}

@@ -1,10 +1,10 @@
 // The one write path for text no person typed into hippo: capture, compaction items and imported agent memories.
-import { isContentWorthStoring } from './memory-quality.js';
-import { RejectedValueError } from './rejection.js';
-import { detectSecret } from './secret-detect.js';
-import { auditRejectionRefusal } from './store/audit-event.js';
-import { stampOriginProject } from './store/entry-row.js';
-import { writeEntryDbOnly } from './store/entry-writes.js';
+import { isContentWorthStoring } from '../core/memory-quality.js';
+import { RejectedValueError } from '../store/rejection.js';
+import { detectSecret } from '../util/secret-detect.js';
+import { auditRejectionRefusal } from '../store/audit-event.js';
+import { stampOriginProject } from '../store/entry-row.js';
+import { writeEntryDbOnly } from '../store/entry-writes.js';
 /** Runs on the caller's handle so it nests in the caller's transaction (writeEntry would open a second handle and wait on that lock); the caller mirrors after commit with an entry it stamped itself. The rejection audit lands inside that transaction, which is safe because a batch that rolls back stays `summarised` and replay writes the audit again. */
 export function gatedWrite(db, hippoRoot, entry, opts) {
     // Off for imported agent memories: a person wrote those notes, and a one-line preference fails the check.

package/dist/trust/quarantine.d.ts

@@ -0,0 +1,4 @@
+/** Quarantine tier (CD5, AT3): pending/approved/rejected record for a memory `remember` flagged as untrusted. */
+export { quarantineScopeFor } from '../store/quarantine.js';
+export declare function isQuarantineScope(scope: string | null | undefined): boolean;
+//# sourceMappingURL=quarantine.d.ts.map