hippo-memory 1.70.0 → 1.71.0

package/dist/store/token-ledger.js

@@ -1,30 +1,9 @@
-/**
- * Token ledger: what memory text hippo hands agents,
- * and how many tokens it costs.
- *
- * One row per block of memory text sent to an agent, on every surface: the
- * per-prompt hook, the block `hippo compact-resume` restores after compaction,
- * `hippo context`, `hippo recall`, the MCP tools and the HTTP API. The ledger
- * answers the question a buyer asks first ("what does this cost me per
- * session?") and is the input for the token-savings evals.
- *
- * Every later model call re-reads a sent block until the host compacts; at session end the worker counts
- * those calls from the transcript as `reread` rows for the {@link REREAD_SURFACES} blocks, dated by call day.
- *
- * It also backs inject-only-on-change: the per-prompt hook compares the
- * hash of the block it is about to send with the last block it sent in the
- * same session and records a `skip` instead of sending it again.
- *
- * Token counts use {@link estimateTokens} (characters / 4), the same estimate
- * every budget in hippo uses. Rows hold counts, surfaces, session ids and
- * hashes, never memory content or query text.
- *
- * DB helpers take the caller's handle; {@link readApiCalls} streams one
- * transcript file. Writes are best-effort at the call sites; a ledger failure
- * must never break recall.
- */
+/** Token ledger: one row per block of memory text sent to an agent on any surface, with its token cost; the input for the token-savings evals.
+ * Backs inject-only-on-change: the hook records a `skip` when the block hash matches the session's last; `reread` rows cover {@link REREAD_SURFACES} blocks.
+ * Counts use {@link estimateTokens} (chars / 4); rows never hold content or query text. Writes are best-effort: a ledger failure must not break recall. */
 import { open } from 'node:fs/promises';
 import { withWriteScope } from '../db/index.js';
+import { onHandle } from './open.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';
@@ -38,9 +17,7 @@ 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;
-/**
- * Append one ledger row and prune rows past {@link TOKEN_LEDGER_RETENTION_DAYS}.
- */
+/** 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();
     insertTokenRow(db, {
@@ -56,11 +33,7 @@ export function recordTokenUse(db, use) {
     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
- * session has injected nothing, a `reset` came after it, or there is no
- * session id (without one, the caller always injects).
- */
+/** The last block this session injected on `surface`, or null if none, a `reset` came after it, or there is no session id (the caller then always injects). */
 export function lastSentState(db, tenantId, sessionId, surface) {
     if (!sessionId)
         return null;
@@ -70,12 +43,8 @@ export function lastSentState(db, tenantId, sessionId, surface) {
     const skips = countSkipsAfter(db, tenantId, sessionId, surface, anchor.id);
     return { hash: anchor.block_hash, skipsSince: Number(skips?.n ?? 0) };
 }
-/**
- * Whether a block identical to the session's last injection should be
- * skipped. `refreshTurns` resends an unchanged block after that many
- * consecutive skips, so a long session still sees its pinned rules near the
- * latest turn; 0 never resends an unchanged block.
- */
+/** Whether a block identical to the session's last injection should be skipped; `refreshTurns` resends it after that many consecutive skips so a long
+ * session still sees its pinned rules, 0 never resends. */
 export function shouldSkipUnchanged(last, hash, refreshTurns) {
     if (!last || last.hash !== hash)
         return false;
@@ -83,10 +52,7 @@ export function shouldSkipUnchanged(last, hash, refreshTurns) {
         return false;
     return true;
 }
-/**
- * Sum the ledger for one tenant since `sinceIso`. Surfaces with no rows are
- * omitted.
- */
+/** Sum the ledger for one tenant since `sinceIso`; surfaces with no rows are omitted. */
 export function summarizeTokenUse(db, tenantId, sinceIso) {
     const rows = surfaceTotals(db, tenantId, sinceIso);
     const bySurface = new Map(rows.map((r) => [r.surface, r]));
@@ -159,11 +125,8 @@ export function isSubagentPayload(stdinText) {
     const agentId = parseHookPayload(stdinText)?.agent_id;
     return isJsonString(agentId) && agentId.trim() !== '';
 }
-/**
- * Ledger totals per session id since `sinceIso`, across every surface.
- * Claude Code hook rows carry the host's session id, which is also the
- * transcript file name, so these join to the host's own usage records.
- */
+/** Ledger totals per session id since `sinceIso`, across surfaces; hook rows carry the host's session id (the transcript file name), so they join to its
+ * usage records. */
 export function tokensBySession(db, tenantId, sinceIso) {
     return sessionTokenRows(db, tenantId, sinceIso).map((r) => ({
         sessionId: r.session_id,
@@ -227,8 +190,14 @@ export function carryingCalls(calls, at) {
         return [];
     return calls.filter((call) => call.at > at && call.compactions === first.compactions);
 }
-/** 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) {
+/** Replace a session's `reread` rows in `hippoRoot`'s store, one per {@link REREAD_SURFACES} surface and UTC day; returns the tokens booked. */
+export function recordRereads(hippoRoot, tenantId, sessionId, calls) {
+    return onHandle(hippoRoot, (db) => {
+        return replaceRereadRows(db, tenantId, sessionId, calls);
+    });
+}
+/** One transaction, so a refused row leaves the session's earlier re-read rows in place. */
+function replaceRereadRows(db, tenantId, sessionId, calls) {
     return withWriteScope(db, 'record_rereads', () => {
         const rows = injectedBlocks(db, tenantId, sessionId, REREAD_SURFACES);
         const days = new Map();

package/dist/store/usage-reports.js

@@ -1,26 +1,18 @@
 // 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 { onHandle } from './open.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 onHandle(hippoRoot, (db) => {
         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 onHandle(hippoRoot, (db) => {
         return summarizeFailures(db, tenantId, sinceIso);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 //# sourceMappingURL=usage-reports.js.map

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

@@ -0,0 +1,46 @@
+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';
+/** What a store's vector index was built by: the stored identity, and whether any vector exists. */
+export interface EmbeddingIndexState {
+    readonly storedModel: string | null;
+    readonly hasVectors: boolean;
+}
+/** The model the index was built by: the stored identity, else the default model when vectors exist. */
+export declare function indexedModel(state: EmbeddingIndexState): string | null;
+/** Whether a vector write under the index identity `model` first drops the stored index, which another model built. */
+export declare function replacesIndex(state: EmbeddingIndexState, model: string): boolean;
+/** hippo.db's index state, the meta row and the EXISTS on one handle. */
+export declare function storedIndexState(hippoRoot: string): EmbeddingIndexState;
+/** Records `identity` as what built the index under `hippoRoot`. */
+export declare function saveIndexIdentity(hippoRoot: string, identity: string): void;
+/** Every stored vector keyed by memory id; `{}` when none. Search reads only the rows it ranks via `loadStoredVectors`. */
+export declare function loadEmbeddingIndex(hippoRoot: string): Record<string, number[]>;
+export interface StoredVectorSummary {
+    readonly ids: Set<string>;
+    readonly dims: number | undefined;
+}
+/** Every stored vector id and the float count of the first row, with no vector decoded. */
+export declare function storedVectorSummary(hippoRoot: string): StoredVectorSummary;
+/** Stored vectors for `ids` only. */
+export declare function loadStoredVectors(hippoRoot: string, ids: readonly string[]): Map<string, number[]>;
+/** `loadStoredVectors` as Float32 views, for a caller that only scores them. */
+export declare function loadStoredVectorViews(hippoRoot: string, ids: readonly string[]): Map<string, Float32Array>;
+/** Replace every stored vector with `index`; `model` defaults to the stored index identity. */
+export declare function saveEmbeddingIndex(hippoRoot: string, index: Record<string, number[]>, model?: string): void;
+/** Inserts or replaces `rows` under `model`, each row its own commit so a failure keeps the rows before it; returns how many it wrote. */
+export declare function saveStoredVectors(hippoRoot: string, rows: Iterable<readonly [string, readonly number[]]>, model: string): number;
+/** Drops the vectors of deleted memories under `hippoRoot`, then returns the ids that still have one. */
+export declare function pruneStoredVectors(hippoRoot: string): Set<string>;
+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 memory in `ids` that has an embedding; returns how many. Rows are read a page at a time. */
+export declare function resetStoredParticles(hippoRoot: string, ids: readonly string[], embeddingIndex: Record<string, number[]>): number;
+/** Stores a first particle for `entry`, placed at `vector`; a memory that has one keeps it. */
+export declare function seedStoredParticle(hippoRoot: string, entry: MemoryEntry, vector: number[]): void;
+//# sourceMappingURL=vector-index.d.ts.map

package/dist/store/vector-index.js

@@ -0,0 +1,170 @@
+// Owns hippo.db's stored vectors, the identity of the model that built them, and the particle rows: every read and write of the three.
+import { getMeta, setMeta, withWriteScope } from '../db/index.js';
+import { onHandle } from './open.js';
+import { DEFAULT_EMBEDDING_MODEL } from './embeddings/local.js';
+import { float32ToBuffer, initializeParticle, loadPhysicsState, resetAllPhysicsState, savePhysicsState } from '../db/physics-state.js';
+import { EMBEDDING_MODEL_META_KEY, deleteOrphanVectors, hasStoredVectors, loadVectors, loadVectorViews, replaceAllVectors, storedVectorDims, storedVectorIds, upsertVectors, } from '../db/vector-store.js';
+import { chunked, selectEntriesByIds } from './entry-reads.js';
+import { MEMORY_SELECT_COLUMNS, rowToEntry } from './rows.js';
+const MAX_BACKFILL_PAGE = 500;
+/** The model the index was built by: the stored identity, else the default model when vectors exist. */
+export function indexedModel(state) {
+    return state.storedModel ?? (state.hasVectors ? DEFAULT_EMBEDDING_MODEL : null);
+}
+/** Whether a vector write under the index identity `model` first drops the stored index, which another model built. */
+export function replacesIndex(state, model) {
+    const indexed = indexedModel(state);
+    return indexed !== null && indexed !== model;
+}
+function embeddingIndexStateOn(db) {
+    return {
+        storedModel: getMeta(db, EMBEDDING_MODEL_META_KEY, '').trim() || null,
+        hasVectors: hasStoredVectors(db),
+    };
+}
+/** hippo.db's index state, the meta row and the EXISTS on one handle. */
+export function storedIndexState(hippoRoot) {
+    return onHandle(hippoRoot, (db) => {
+        return embeddingIndexStateOn(db);
+    });
+}
+/** Records `identity` as what built the index under `hippoRoot`. */
+export function saveIndexIdentity(hippoRoot, identity) {
+    onHandle(hippoRoot, (db) => {
+        setMeta(db, EMBEDDING_MODEL_META_KEY, identity);
+    });
+}
+/** Every stored vector keyed by memory id; `{}` when none. Search reads only the rows it ranks via `loadStoredVectors`. */
+export function loadEmbeddingIndex(hippoRoot) {
+    return onHandle(hippoRoot, (db) => {
+        return Object.fromEntries(loadVectors(db));
+    });
+}
+/** Every stored vector id and the float count of the first row, with no vector decoded. */
+export function storedVectorSummary(hippoRoot) {
+    return onHandle(hippoRoot, (db) => {
+        return { ids: storedVectorIds(db), dims: storedVectorDims(db) };
+    });
+}
+/** Stored vectors for `ids` only. */
+export function loadStoredVectors(hippoRoot, ids) {
+    if (ids.length === 0)
+        return new Map();
+    return onHandle(hippoRoot, (db) => {
+        return loadVectors(db, ids);
+    });
+}
+/** `loadStoredVectors` as Float32 views, for a caller that only scores them. */
+export function loadStoredVectorViews(hippoRoot, ids) {
+    if (ids.length === 0)
+        return new Map();
+    return onHandle(hippoRoot, (db) => {
+        return loadVectorViews(db, ids);
+    });
+}
+/** Replace every stored vector with `index`; `model` defaults to the stored index identity. */
+export function saveEmbeddingIndex(hippoRoot, index, model) {
+    onHandle(hippoRoot, (db) => {
+        replaceAllVectors(db, index, model ?? getMeta(db, EMBEDDING_MODEL_META_KEY, ''));
+    });
+}
+/** Inserts or replaces `rows` under `model`, each row its own commit so a failure keeps the rows before it; returns how many it wrote. */
+export function saveStoredVectors(hippoRoot, rows, model) {
+    return onHandle(hippoRoot, (db) => {
+        return upsertVectors(db, rows, model);
+    });
+}
+/** Drops the vectors of deleted memories under `hippoRoot`, then returns the ids that still have one. */
+export function pruneStoredVectors(hippoRoot) {
+    return onHandle(hippoRoot, (db) => {
+        deleteOrphanVectors(db);
+        return storedVectorIds(db);
+    });
+}
+export function entriesWithoutVectorAt(db, query) {
+    if (!Number.isInteger(query.limit))
+        throw new RangeError('limit must be an integer');
+    const limit = Math.max(1, Math.min(query.limit, MAX_BACKFILL_PAGE));
+    const tenantClause = query.tenantId === undefined ? '' : ' AND tenant_id = ?';
+    const tenantArgs = query.tenantId === undefined ? [] : [query.tenantId];
+    // SAFETY: selects exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
+    const rows = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id > ?${tenantClause}
+       AND NOT EXISTS (SELECT 1 FROM memory_vectors v WHERE v.memory_id = memories.id AND v.model = ?)
+     ORDER BY id LIMIT ?`).all(query.afterId ?? '', ...tenantArgs, query.model, limit);
+    return rows.map(rowToEntry);
+}
+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);
+        for (const row of rows)
+            owned.add(row.id);
+    }
+    return owned;
+}
+// savePhysicsState opens its own transaction and overwrites, so the first particle for a memory is inserted here instead.
+function insertNewParticles(db, rows) {
+    const stmt = db.prepare(`
+    INSERT INTO memory_physics (memory_id, position_blob, velocity_blob, mass, charge, temperature, last_simulation)
+    VALUES (?, ?, ?, ?, ?, ?, ?) ON CONFLICT(memory_id) DO NOTHING
+  `);
+    for (const { memoryId, particle: p } of rows) {
+        if (p)
+            stmt.run(memoryId, float32ToBuffer(p.position), float32ToBuffer(p.velocity), p.mass, p.charge, p.temperature, p.lastSimulation);
+    }
+}
+export function writeVectorsAt(db, write) {
+    return withWriteScope(db, 'write_vectors', () => {
+        const replaces = replacesIndex(embeddingIndexStateOn(db), write.model);
+        if (replaces && !write.replaceIndex)
+            return { written: 0, modelMismatch: true };
+        const owned = ownedIds(db, write.rows.map((r) => r.memoryId), write.tenantId);
+        const rows = write.rows.filter((r) => owned.has(r.memoryId) && r.vector.length > 0 && r.vector.every(Number.isFinite));
+        if (rows.length === 0)
+            return { written: 0, modelMismatch: false };
+        if (replaces)
+            db.exec('DELETE FROM memory_vectors; DELETE FROM memory_physics;');
+        const written = upsertVectors(db, rows.map((r) => [r.memoryId, r.vector]), write.model);
+        insertNewParticles(db, rows);
+        setMeta(db, EMBEDDING_MODEL_META_KEY, write.model);
+        return { written, modelMismatch: false };
+    });
+}
+/** Every particle stored under `hippoRoot`. */
+export function loadStoredParticles(hippoRoot) {
+    return onHandle(hippoRoot, (db) => {
+        return Array.from(loadPhysicsState(db).values());
+    });
+}
+/** Writes `particles` over their stored state under `hippoRoot`, as one batch. */
+export function saveStoredParticles(hippoRoot, particles) {
+    onHandle(hippoRoot, (db) => {
+        savePhysicsState(db, particles);
+    });
+}
+const PARTICLE_PAGE = 64;
+function* entriesInPages(db, ids) {
+    for (const page of chunked(ids, PARTICLE_PAGE)) {
+        const rows = selectEntriesByIds(db, page);
+        for (const id of page) {
+            const entry = rows.get(id);
+            if (entry)
+                yield entry;
+        }
+    }
+}
+/** Replaces every particle under `hippoRoot` with a fresh one per memory in `ids` that has an embedding; returns how many. Rows are read a page at a time. */
+export function resetStoredParticles(hippoRoot, ids, embeddingIndex) {
+    return onHandle(hippoRoot, (db) => {
+        return resetAllPhysicsState(db, entriesInPages(db, ids), embeddingIndex);
+    });
+}
+/** Stores a first particle for `entry`, placed at `vector`; a memory that has one keeps it. */
+export function seedStoredParticle(hippoRoot, entry, vector) {
+    onHandle(hippoRoot, (db) => {
+        if (!loadPhysicsState(db, [entry.id]).has(entry.id))
+            savePhysicsState(db, [initializeParticle(entry, vector)]);
+    });
+}
+//# sourceMappingURL=vector-index.js.map

package/dist/store/working-memory.d.ts

@@ -1,10 +1,4 @@
-/**
- * Working Memory — bounded buffer for current-state notes.
- *
- * Separate from long-term semantic memory. Entries are scoped,
- * importance-ranked, and automatically evicted when the buffer
- * exceeds WM_MAX_ENTRIES per scope.
- */
+/** Working Memory: bounded buffer for current-state notes, separate from long-term memory; scoped, importance-ranked, evicted past WM_MAX_ENTRIES per scope. */
 import type { JsonValue } from '../util/json.js';
 export declare const WM_MAX_ENTRIES = 20;
 export type JsonObject = {
@@ -21,12 +15,8 @@ export interface WorkingMemoryItem {
     createdAt: string;
     updatedAt: string;
 }
-/**
- * Push a new entry into working memory.
- * If the scope exceeds WM_MAX_ENTRIES, the lowest-importance entry
- * is evicted (ties broken by oldest created_at).
- * Returns the new row ID.
- */
+/** Push a new entry into working memory; past WM_MAX_ENTRIES the scope's lowest-importance entry is evicted (ties: oldest created_at). Returns the new
+ * row ID. */
 export declare function wmPush(hippoRoot: string, opts: {
     scope: string;
     content: string;
@@ -36,29 +26,20 @@ export declare function wmPush(hippoRoot: string, opts: {
     metadata?: JsonObject;
     tenantId?: string;
 }): number;
-/**
- * Read working memory entries, sorted by importance DESC.
- */
+/** Read working memory entries, sorted by importance DESC. */
 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.
- */
+/** Clear (delete) working memory entries. Returns the count deleted. */
 export declare function wmClear(hippoRoot: string, opts?: {
     scope?: string;
     sessionId?: string;
     tenantId?: string;
 }): number;
-/**
- * Flush working memory — delete entries after session end.
- * Functionally identical to wmClear but semantically distinct:
- * used at session boundaries to discard ephemeral state.
- * Returns the count flushed.
- */
+/** Flush working memory after session end: same as wmClear, but marks the session-boundary discard of ephemeral state. Returns the count flushed. */
 export declare function wmFlush(hippoRoot: string, opts?: {
     scope?: string;
     sessionId?: string;

package/dist/store/working-memory.js

@@ -1,21 +1,14 @@
-/**
- * Working Memory — bounded buffer for current-state notes.
- *
- * Separate from long-term semantic memory. Entries are scoped,
- * importance-ranked, and automatically evicted when the buffer
- * exceeds WM_MAX_ENTRIES per scope.
- */
-import { closeHippoDb, withWriteScope } from '../db/index.js';
-import { openStore } from './open.js';
+/** Working Memory: bounded buffer for current-state notes, separate from long-term memory; scoped, importance-ranked, evicted past WM_MAX_ENTRIES per scope. */
+import { withWriteScope } from '../db/index.js';
+import { onHandle, 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 = {};
     try {
-        // SAFETY: metadata_json is always written by wmPush via
-        // JSON.stringify(opts.metadata ?? {}), so a successful parse yields a
-        // plain JSON object; malformed content falls through to the catch below.
+        // SAFETY: metadata_json is always written by wmPush via JSON.stringify(opts.metadata ?? {}), so a successful parse yields a plain JSON object;
+        // malformed content falls through to the catch below.
         metadata = JSON.parse(row.metadata_json);
     }
     catch {
@@ -34,15 +27,10 @@ function rowToItem(row) {
         updatedAt: row.updated_at,
     };
 }
-/**
- * Push a new entry into working memory.
- * If the scope exceeds WM_MAX_ENTRIES, the lowest-importance entry
- * is evicted (ties broken by oldest created_at).
- * Returns the new row ID.
- */
+/** Push a new entry into working memory; past WM_MAX_ENTRIES the scope's lowest-importance entry is evicted (ties: oldest created_at). Returns the new
+ * row ID. */
 export function wmPush(hippoRoot, opts) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const now = new Date().toISOString();
         const importance = opts.importance ?? 0;
         const tenantId = opts.tenantId ?? resolveTenantId({});
@@ -55,16 +43,11 @@ export function wmPush(hippoRoot, opts) {
             evictOverCapacity(db, opts.scope, tenantId);
             return id;
         });
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 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.
+    // Evict if over capacity for this scope.
+    // SAFETY: `COUNT(*) AS cnt` always returns exactly one row { cnt }, so `.get()` never yields undefined.
     const countRow = db.prepare(`
     SELECT COUNT(*) AS cnt FROM working_memory WHERE scope = ? AND tenant_id = ?
   `).get(scope, tenantId);
@@ -82,12 +65,9 @@ function evictOverCapacity(db, scope, tenantId) {
     `).run(scope, tenantId, excess);
     }
 }
-/**
- * Read working memory entries, sorted by importance DESC.
- */
+/** Read working memory entries, sorted by importance DESC. */
 export function wmRead(hippoRoot, opts) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const clauses = ['tenant_id = ?'];
         const params = [opts?.tenantId ?? resolveTenantId({})];
         if (opts?.scope) {
@@ -111,17 +91,11 @@ export function wmRead(hippoRoot, opts) {
       LIMIT ?
     `).all(...params);
         return rows.map(rowToItem);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/**
- * Clear (delete) working memory entries. Returns the count deleted.
- */
+/** Clear (delete) working memory entries. Returns the count deleted. */
 export function wmClear(hippoRoot, opts) {
-    const db = openStore(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         const clauses = ['tenant_id = ?'];
         const params = [opts?.tenantId ?? resolveTenantId({})];
         if (opts?.scope) {
@@ -135,17 +109,9 @@ export function wmClear(hippoRoot, opts) {
         const where = clauses.length > 0 ? `WHERE ${clauses.join(' AND ')}` : '';
         const result = db.prepare(`DELETE FROM working_memory ${where}`).run(...params);
         return Number(result.changes ?? 0);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/**
- * Flush working memory — delete entries after session end.
- * Functionally identical to wmClear but semantically distinct:
- * used at session boundaries to discard ephemeral state.
- * Returns the count flushed.
- */
+/** Flush working memory after session end: same as wmClear, but marks the session-boundary discard of ephemeral state. Returns the count flushed. */
 export function wmFlush(hippoRoot, opts) {
     return wmClear(hippoRoot, opts);
 }

package/dist/store/yaml.d.ts

@@ -1,8 +1,4 @@
-/**
- * Minimal YAML frontmatter serializer/deserializer.
- * No external deps. Handles simple key-value + arrays (inline only).
- * Sufficient for the MemoryEntry frontmatter schema.
- */
+/** Minimal YAML frontmatter serializer/deserializer with no external deps: simple key-value pairs and inline arrays, enough for the MemoryEntry schema. */
 type YamlValue = string | number | boolean | null | string[] | number[];
 export declare function dumpFrontmatter(obj: Record<string, YamlValue>): string;
 export interface ParsedFrontmatter {

package/dist/store/yaml.js

@@ -1,13 +1,9 @@
-/**
- * Minimal YAML frontmatter serializer/deserializer.
- * No external deps. Handles simple key-value + arrays (inline only).
- * Sufficient for the MemoryEntry frontmatter schema.
- */
+/** Minimal YAML frontmatter serializer/deserializer with no external deps: simple key-value pairs and inline arrays, enough for the MemoryEntry schema. */
 const SCALAR_LOOKALIKE = /^(null|true|false|-?\d+(\.\d+)?)$/;
 const UNESCAPES = new Map([['\\', '\\'], ['"', '"'], ['n', '\n'], ['r', '\r']]);
 function escapeString(s) {
     // A string that reads as null, a boolean or a number is quoted so it comes back a string.
-    if (/[:#\[\]{},\n\r"']/.test(s) || s.trim() !== s || s === '' || SCALAR_LOOKALIKE.test(s)) {
+    if (/[:#[\]{},\n\r"']/.test(s) || s.trim() !== s || s === '' || SCALAR_LOOKALIKE.test(s)) {
         const escaped = s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n').replace(/\r/g, '\\r');
         return `"${escaped}"`;
     }

package/dist/support-bundle.js

@@ -1,4 +1,5 @@
-/** `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. */
+/** `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 './util/env.js';
 import * as fs from 'fs';
 import * as os from 'os';
@@ -6,7 +7,7 @@ import * as path from 'path';
 import { pathToFileURL } from 'url';
 import { findHippoStoreDir, isGlobalStoreRoot } from './core/project-identity.js';
 import { realpathOrResolve } from './util/real-path.js';
-import { getGlobalRoot } from './sharing/shared.js';
+import { getGlobalRoot } from './sharing/global-store.js';
 import { isInitialized } from './store/open.js';
 import { readStoreInventory } from './store/diagnostics.js';
 import { runDoctor } from './doctor.js';
@@ -117,12 +118,13 @@ function listLogFileNames(dir) {
         .sort();
 }
 function tailLogFile(file) {
-    const size = fs.statSync(file).size;
-    const readSize = Math.min(size, TAIL_MAX_BYTES);
-    const startedMidFile = size > TAIL_MAX_BYTES;
     const fd = fs.openSync(file, 'r');
     let text;
+    let startedMidFile;
     try {
+        const size = fs.fstatSync(fd).size;
+        const readSize = Math.min(size, TAIL_MAX_BYTES);
+        startedMidFile = size > TAIL_MAX_BYTES;
         const buf = Buffer.alloc(readSize);
         fs.readSync(fd, buf, 0, readSize, size - readSize);
         text = buf.toString('utf8');

package/dist/trust/reject-flow.js

@@ -18,9 +18,7 @@ function assertRejectOpts(opts) {
         throw new Error('reject accepts either a memory id or --value, not both.');
     }
     if (opts.value !== undefined && normalizeValueForRejection(opts.value).length === 0) {
-        // Direct api callers can pass strings the CLI flag parser would have
-        // refused; an empty-normalized tombstone would refuse nothing meaningful
-        // and pollute the listing.
+        // Direct api callers can pass strings the CLI flag parser would refuse; an empty-normalized tombstone would refuse nothing and pollute the listing.
         throw new Error('reject --value requires non-empty content.');
     }
 }

package/dist/util/anthropic-messages.js

@@ -1,9 +1,19 @@
 /** The one Anthropic Messages client: sends one user prompt and returns the reply text or a typed failure the caller reacts to. */
 import { fetchWithRetry, llmTimeoutMs } from './http-retry.js';
 import { errorMessage } from './log.js';
+import { readCappedJson } from './capped-json.js';
+import { isJsonObject, isJsonString } from './json.js';
 const MESSAGES_URL = 'https://api.anthropic.com/v1/messages';
 const API_VERSION = '2023-06-01';
 const DEFAULT_MODEL = 'claude-sonnet-4-6';
+// Callers ask for at most 1,200 tokens, a reply of a few KB; 1 MiB leaves room for a verbose envelope.
+const MAX_REPLY_BYTES = 1024 * 1024;
+/** The first content block's text, trimmed; empty when the reply has no such block. */
+function firstText(reply) {
+    const first = Array.isArray(reply.content) ? reply.content[0] : undefined;
+    const text = isJsonObject(first) ? first.text : undefined;
+    return isJsonString(text) ? text.trim() : '';
+}
 /** The reply's first text block, trimmed (empty when the reply has none); never throws. */
 export async function sendAnthropicMessage(req) {
     let res;
@@ -28,8 +38,10 @@ export async function sendAnthropicMessage(req) {
     if (!res.ok)
         return { ok: false, failure: { kind: 'http', status: res.status } };
     try {
-        const data = await res.json();
-        return { ok: true, text: data.content?.[0]?.text?.trim() ?? '' };
+        const data = await readCappedJson(res, MAX_REPLY_BYTES);
+        if (!isJsonObject(data))
+            return { ok: false, failure: { kind: 'unreadable', message: 'the reply is not a JSON object' } };
+        return { ok: true, text: firstText(data) };
     }
     catch (err) {
         return { ok: false, failure: { kind: 'unreadable', message: errorMessage(err) } };