hippo-memory 1.72.0 → 2.1.0

package/dist/db/request-stores.d.ts

@@ -4,9 +4,15 @@ import { type RequestScope } from '../util/request-scope.js';
 export interface RequestStoresOptions {
     /** Lock wait of every open in the scope that does not pass its own. */
     readonly busyWaitMs?: number;
-    /** Set for hook scopes: after one lock wait runs out, {@link RequestStores.noteBusy} makes the scope's later writes skip at once. */
+    /**
+     * Set for hook scopes: after one lock wait runs out, {@link RequestStores.noteBusy} makes the scope's later writes
+     * skip at once.
+     */
     readonly failFastWhenBusy?: boolean;
-    /** The store whose open-time setup another connection has already run, so an open in this scope skips it: a store worker's reader, which cannot write it. */
+    /**
+     * The store whose open-time setup another connection has already run, so an open in this scope skips it: a store
+     * worker's reader, which cannot write it.
+     */
     readonly setupDoneFor?: string;
 }
 /** The handles one request opened, keyed by resolved store path and lock wait. */
@@ -15,6 +21,7 @@ export declare class RequestStores implements RequestScope {
     readonly busyWaitMs: number | undefined;
     readonly requestId: string | undefined;
     readonly deadline: import("../util/request-scope.js").RequestDeadline | undefined;
+    readonly signal: AbortSignal | undefined;
     readonly setupDoneFor: string | undefined;
     constructor(opts?: RequestStoresOptions);
     get closed(): boolean;
@@ -30,13 +37,21 @@ export declare class RequestStores implements RequestScope {
     noteBusy(): void;
     close(): void;
 }
-/** Runs `fn` in a request scope whose handles close when `fn` settles; inside an open scope `fn` joins it and `opts` is ignored. */
+/**
+ * Runs `fn` in a request scope whose handles close when `fn` settles; inside an open scope `fn` joins it and `opts` is
+ * ignored.
+ */
 export declare function runWithRequestStores<T>(fn: () => T | Promise<T>, opts?: RequestStoresOptions): Promise<T>;
-/** runWithRequestStores for a synchronous `fn`, so a batch called from outside any request still opens each store once. */
+/**
+ * runWithRequestStores for a synchronous `fn`, so a batch called from outside any request still opens each store once.
+ */
 export declare function withRequestStoresSync<T>(fn: () => T): T;
 /** The scope this code runs in, if any. A closed scope still answers: its `get` falls through to a plain open. */
 export declare function currentRequestStores(): RequestStores | undefined;
-/** Runs `fn` outside every store scope, for a connection that must outlive the request that happens to open it; its log lines keep the request's id. */
+/**
+ * Runs `fn` outside every store scope, for a connection that must outlive the request that happens to open it; its log
+ * lines keep the request's id.
+ */
 export declare function outsideRequestStores<T>(fn: () => T): T;
 /** Whether a scope owns `db` and will close it itself. */
 export declare function isScopedHandle(db: DatabaseSyncLike): boolean;

package/dist/db/request-stores.js

@@ -1,7 +1,8 @@
-// One store handle per store for each request (HTTP call, MCP tool call, scoped CLI command), opened lazily and closed with it.
+// One store handle per store for each request (HTTP call, MCP tool call, scoped CLI command), opened lazily and closed
+// with it.
 import * as path from 'node:path';
 import { connectWithFacts, getHippoDbPath } from './connect.js';
-import { currentDeadline, currentRequestId, requestScopes } from '../util/request-scope.js';
+import { currentDeadline, currentRequestId, currentSignal, requestScopes, } from '../util/request-scope.js';
 // Handles a scope owns, so closeHippoDb leaves them open for the rest of the request.
 const scopedHandles = new WeakSet();
 // process.exit skips every finally, so one exit listener closes the handles of scopes still open.
@@ -24,6 +25,7 @@ export class RequestStores {
     // Taken from the scope this one opens inside, so the request's log lines keep their id.
     requestId = currentRequestId();
     deadline = currentDeadline();
+    signal = currentSignal();
     setupDoneFor;
     #failFastWhenBusy;
     #handles = new Map();
@@ -78,7 +80,10 @@ export class RequestStores {
         this.#handles.clear();
     }
 }
-/** Runs `fn` in a request scope whose handles close when `fn` settles; inside an open scope `fn` joins it and `opts` is ignored. */
+/**
+ * Runs `fn` in a request scope whose handles close when `fn` settles; inside an open scope `fn` joins it and `opts` is
+ * ignored.
+ */
 export async function runWithRequestStores(fn, opts) {
     const outer = currentRequestStores();
     if (outer && !outer.closed)
@@ -93,7 +98,9 @@ export async function runWithRequestStores(fn, opts) {
         }
     });
 }
-/** runWithRequestStores for a synchronous `fn`, so a batch called from outside any request still opens each store once. */
+/**
+ * runWithRequestStores for a synchronous `fn`, so a batch called from outside any request still opens each store once.
+ */
 export function withRequestStoresSync(fn) {
     const outer = currentRequestStores();
     if (outer && !outer.closed)
@@ -111,7 +118,10 @@ export function currentRequestStores() {
     const scope = requestScopes.getStore();
     return scope instanceof RequestStores ? scope : undefined;
 }
-/** Runs `fn` outside every store scope, for a connection that must outlive the request that happens to open it; its log lines keep the request's id. */
+/**
+ * Runs `fn` outside every store scope, for a connection that must outlive the request that happens to open it; its log
+ * lines keep the request's id.
+ */
 export function outsideRequestStores(fn) {
     return requestScopes.run({ requestId: currentRequestId() }, fn);
 }

package/dist/db/tables.d.ts

@@ -7,7 +7,8 @@ export declare function tableExists(db: DatabaseSyncLike, tableName: string): bo
 export declare function listTableNames(db: DatabaseSyncLike): string[];
 /** Row count of one table; null when the table is missing or unreadable, which callers show as unknown. */
 export declare function countTableRows(db: DatabaseSyncLike, table: string): number | null;
-/** Sleep runs a store keeps; stats.json lists exactly these, so a recall's stats rewrite reads a fixed number of rows. */
+/** Sleep runs a store keeps; stats.json lists exactly these,
+ * so a recall's stats rewrite reads a fixed number of rows. */
 export declare const CONSOLIDATION_RUNS_KEPT = 50;
 export declare function pruneConsolidationRuns(db: DatabaseSyncLike, keep?: number): void;
 //# sourceMappingURL=tables.d.ts.map

package/dist/db/tables.js

@@ -1,4 +1,4 @@
-import { errorCode, log } from '../util/log.js';
+import { errorCode, log, errorFields } from '../util/log.js';
 /** Column names of one table; empty when the table is missing. */
 export function tableColumns(db, tableName) {
     if (!/^[a-z_]+$/i.test(tableName))
@@ -21,7 +21,10 @@ export function tableExists(db, tableName) {
 /** Names of the real tables, without sqlite internals and FTS virtual tables. */
 export function listTableNames(db) {
     // SAFETY: each row's shape matches the single `name` column named in the SELECT below.
-    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();
+    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);
 }
 /** Row count of one table; null when the table is missing or unreadable, which callers show as unknown. */
@@ -33,11 +36,16 @@ export function countTableRows(db, table) {
     }
     catch (err) {
         // Callers treat an uncountable table as unknown; the bundle and doctor still finish.
-        log.warn(`could not count rows in table ${table}`, { table, code: errorCode(err) || 'unknown' });
+        log.warn(`could not count rows in table ${table}`, {
+            table,
+            code: errorCode(err) || 'unknown',
+            ...errorFields(err),
+        });
         return null;
     }
 }
-/** Sleep runs a store keeps; stats.json lists exactly these, so a recall's stats rewrite reads a fixed number of rows. */
+/** Sleep runs a store keeps; stats.json lists exactly these,
+ * so a recall's stats rewrite reads a fixed number of rows. */
 export const CONSOLIDATION_RUNS_KEPT = 50;
 export function pruneConsolidationRuns(db, keep = CONSOLIDATION_RUNS_KEPT) {
     db.prepare(`

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

@@ -1,4 +1,7 @@
-/** Embedding vectors in the `memory_vectors` table: one Float32 BLOB per memory id, plus the one-time import of the old JSON index. */
+/**
+ * Embedding vectors in the `memory_vectors` table: one Float32 BLOB per memory id, plus the one-time import of the old
+ * JSON index.
+ */
 import type { DatabaseSyncLike } from './index.js';
 export declare const EMBEDDING_MODEL_META_KEY = "embedding_model";
 export declare const MEMORY_VECTORS_DDL = "\n  CREATE TABLE IF NOT EXISTS memory_vectors (\n    memory_id TEXT PRIMARY KEY,\n    model     TEXT NOT NULL,\n    dim       INTEGER NOT NULL,\n    vector    BLOB NOT NULL\n  );\n  CREATE TRIGGER IF NOT EXISTS trg_memory_vectors_delete AFTER DELETE ON memories BEGIN\n    DELETE FROM memory_vectors WHERE memory_id = old.id;\n  END;\n";
@@ -27,13 +30,19 @@ export interface VectorRow {
     readonly id: string;
     readonly vector: Float32Array;
 }
-/** The `k` rows closest to `query` by cosine, best first; ties go to the smaller id, so row order never changes the top k.
- *  The query rounds to Float32 as stored vectors are, and scores add up in float64, so every store that feeds it the same bytes ranks alike. */
+/**
+ * The `k` rows closest to `query` by cosine, best first; ties go to the smaller id, so row order never changes the top
+ * k.
+ * The query rounds to Float32 as stored vectors are, and scores add up in float64, so every store that feeds it the
+ * same bytes ranks alike.
+ */
 export declare function rankVectorRows(query: readonly number[], rows: Iterable<VectorRow>, k: number): VectorMatch[];
 /** The `k` stored vectors closest to `query` among `memories m` rows passing `where` (SQL starting with ` AND`).
  *  Filters run before the cut, so rows a caller may not see can never push admitted rows out of the top k. */
 export declare function topVectorMatches(db: DatabaseSyncLike, query: readonly number[], k: number, where: string, params: readonly (string | number)[]): Promise<VectorMatch[]>;
 /** Move a legacy `embeddings.json` into `memory_vectors`, then keep the file as `embeddings.json.imported-<stamp>`.
- *  Runs after the migration commits, so the rename never outlives rolled-back rows; a file an older binary writes later imports the same way. */
+ * Runs after the migration commits, so the rename never outlives rolled-back rows; a file an older binary writes later
+ * imports the same way.
+ */
 export declare function importLegacyEmbeddingIndex(db: DatabaseSyncLike, hippoRoot: string): void;
 //# sourceMappingURL=vector-store.d.ts.map

package/dist/db/vector-store.js

@@ -1,8 +1,12 @@
-/** Embedding vectors in the `memory_vectors` table: one Float32 BLOB per memory id, plus the one-time import of the old JSON index. */
+/**
+ * Embedding vectors in the `memory_vectors` table: one Float32 BLOB per memory id, plus the one-time import of the old
+ * JSON index.
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import { withWriteScope } from './busy.js';
 import { errorCode, errorFields, log } from '../util/log.js';
+import { placeholders } from '../util/sql.js';
 /** Legacy whole-file index; imported once into `memory_vectors`, then kept beside the store as a renamed backup. */
 const LEGACY_EMBEDDINGS_FILE = 'embeddings.json';
 export const EMBEDDING_MODEL_META_KEY = 'embedding_model';
@@ -56,8 +60,9 @@ export function deleteOrphanVectors(db) {
 function eachStoredVector(db, ids, take) {
     const read = (rows) => {
         // SAFETY: both SELECTs below name exactly these two columns; node:sqlite returns BLOBs as Uint8Array.
-        for (const row of rows)
+        for (const row of rows) {
             take(row.memory_id, decodeVector(row.vector));
+        }
     };
     if (ids === undefined) {
         read(db.prepare('SELECT memory_id, vector FROM memory_vectors').iterate());
@@ -66,7 +71,9 @@ function eachStoredVector(db, ids, take) {
     const unique = [...new Set(ids)];
     for (let i = 0; i < unique.length; i += ID_CHUNK) {
         const chunk = unique.slice(i, i + ID_CHUNK);
-        read(db.prepare(`SELECT memory_id, vector FROM memory_vectors WHERE memory_id IN (${chunk.map(() => '?').join(', ')})`).all(...chunk));
+        read(db
+            .prepare(`SELECT memory_id, vector FROM memory_vectors WHERE memory_id IN (${placeholders(chunk.length)})`)
+            .all(...chunk));
     }
 }
 /** Vectors for `ids`, or every stored vector when `ids` is omitted. */
@@ -94,8 +101,12 @@ export function storedVectorDims(db) {
 export function hasStoredVectors(db) {
     return db.prepare('SELECT 1 FROM memory_vectors LIMIT 1').get() !== undefined;
 }
-/** The `k` rows closest to `query` by cosine, best first; ties go to the smaller id, so row order never changes the top k.
- *  The query rounds to Float32 as stored vectors are, and scores add up in float64, so every store that feeds it the same bytes ranks alike. */
+/**
+ * The `k` rows closest to `query` by cosine, best first; ties go to the smaller id, so row order never changes the top
+ * k.
+ * The query rounds to Float32 as stored vectors are, and scores add up in float64, so every store that feeds it the
+ * same bytes ranks alike.
+ */
 export function rankVectorRows(query, rows, k) {
     const best = bestMatches(query, k);
     if (!best)
@@ -190,7 +201,9 @@ function stamp() {
 }
 // The codes a rename gets when another process holds the file open (Windows); any other failure would fail a copy too.
 const RENAME_BLOCKED_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);
-/** Rename `fp` to `aside`; a rename blocked by an open handle falls back to a copy, so the bytes are kept either way. */
+/**
+ * Rename `fp` to `aside`; a rename blocked by an open handle falls back to a copy, so the bytes are kept either way.
+ */
 function moveAside(fp, aside) {
     try {
         fs.renameSync(fp, aside);
@@ -202,7 +215,10 @@ function moveAside(fp, aside) {
             return false;
         if (!RENAME_BLOCKED_CODES.has(code))
             throw err;
-        log.warn(`could not rename ${path.basename(fp)} aside (${code}); copying it instead`, { path: fp, ...errorFields(err) });
+        log.warn(`could not rename ${path.basename(fp)} aside (${code}); copying it instead`, {
+            path: fp,
+            ...errorFields(err),
+        });
         fs.copyFileSync(fp, aside, fs.constants.COPYFILE_EXCL);
         try {
             fs.rmSync(fp, { force: true });
@@ -215,7 +231,8 @@ function moveAside(fp, aside) {
         return true;
     }
 }
-// The old writer only wrote a plain object of id to number[]; any other shape is corrupt, and non-numeric entries are dropped.
+// The old writer only wrote a plain object of id to number[]; any other shape is corrupt, and non-numeric entries are
+// dropped.
 function parseLegacyIndex(raw) {
     let parsed;
     try {
@@ -234,7 +251,9 @@ function parseLegacyIndex(raw) {
     return index;
 }
 /** Move a legacy `embeddings.json` into `memory_vectors`, then keep the file as `embeddings.json.imported-<stamp>`.
- *  Runs after the migration commits, so the rename never outlives rolled-back rows; a file an older binary writes later imports the same way. */
+ * Runs after the migration commits, so the rename never outlives rolled-back rows; a file an older binary writes later
+ * imports the same way.
+ */
 export function importLegacyEmbeddingIndex(db, hippoRoot) {
     const fp = path.join(hippoRoot, LEGACY_EMBEDDINGS_FILE);
     let raw;
@@ -251,17 +270,19 @@ export function importLegacyEmbeddingIndex(db, hippoRoot) {
         const aside = `${fp}.corrupt-${stamp()}`;
         if (!moveAside(fp, aside))
             return;
-        log.error(`${LEGACY_EMBEDDINGS_FILE} could not be parsed; kept it as ${path.basename(aside)} and the next embed rebuilds the index`, { hippoRoot });
-        db.prepare(`INSERT INTO meta(key, value) VALUES(?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value`)
-            .run(EMBEDDING_MODEL_META_KEY, QUARANTINED_INDEX_IDENTITY);
+        log.error(`${LEGACY_EMBEDDINGS_FILE} could not be parsed; kept it as ${path.basename(aside)} and the next embed rebuilds ` +
+            `the index`, { hippoRoot });
+        db.prepare(`INSERT INTO meta(key, value) VALUES(?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value`).run(EMBEDDING_MODEL_META_KEY, QUARANTINED_INDEX_IDENTITY);
         return;
     }
     // SAFETY: the SELECT names exactly the one column read.
-    const model = db.prepare(`SELECT value FROM meta WHERE key = ?`).get(EMBEDDING_MODEL_META_KEY)?.value ?? '';
+    const model = db.prepare(`SELECT value FROM meta WHERE key = ?`).get(EMBEDDING_MODEL_META_KEY)
+        ?.value ?? '';
     const written = withWriteScope(db, 'import_legacy_vectors', () => upsertVectors(db, index, model));
     const backup = `${fp}.imported-${stamp()}`;
     if (moveAside(fp, backup)) {
-        log.info(`moved ${written} vectors from ${LEGACY_EMBEDDINGS_FILE} into the store; the file is kept as ${path.basename(backup)}`, { hippoRoot });
+        log.info(`moved ${written} vectors from ${LEGACY_EMBEDDINGS_FILE} into the store; the file is kept as ` +
+            `${path.basename(backup)}`, { hippoRoot });
     }
 }
 //# sourceMappingURL=vector-store.js.map

package/dist/db/wal-checkpointer.d.ts

@@ -6,6 +6,7 @@ export interface WalCheckpointer {
 }
 /** The wal_autocheckpoint value for a new connection to `dbPath` in this process. */
 export declare function autoCheckpointPages(dbPath: string): number;
-/** Checkpoints `dbPath` off the calling thread until `stop()`; the worker starts with the first checkpoint that is due. */
+/** Checkpoints `dbPath` off the calling thread until `stop()`;
+ * the worker starts with the first checkpoint that is due. */
 export declare function startWalCheckpointer(dbPath: string): WalCheckpointer;
 //# sourceMappingURL=wal-checkpointer.d.ts.map

package/dist/db/wal-checkpointer.js

@@ -1,7 +1,8 @@
-// A served store's WAL is checkpointed on a worker thread: the fsync calls of a checkpoint would otherwise stall every request on the event loop.
+// A served store's WAL is checkpointed on a worker thread: the fsync calls of a checkpoint would otherwise stall every
+// request on the event loop.
 import * as path from 'node:path';
 import { Worker } from 'node:worker_threads';
-import { errorMessage, log } from '../util/log.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 import { DEFAULT_BUSY_WAIT_MS } from './busy.js';
 // WAL pages at which a connection checkpoints inside its own commit.
 const INLINE_CHECKPOINT_PAGES = 100;
@@ -43,7 +44,19 @@ const backgrounded = new Set();
 export function autoCheckpointPages(dbPath) {
     return backgrounded.has(path.resolve(dbPath)) ? BACKSTOP_CHECKPOINT_PAGES : INLINE_CHECKPOINT_PAGES;
 }
-/** Checkpoints `dbPath` off the calling thread until `stop()`; the worker starts with the first checkpoint that is due. */
+/** An explicit execArgv keeps the parent's loaders out of the
+ * worker and silences its repeat of the node:sqlite warning. */
+function newCheckpointWorker(key) {
+    const started = new Worker(WORKER_SOURCE, {
+        eval: true,
+        execArgv: ['--no-warnings'],
+        workerData: { dbPath: key, maxPasses: MAX_PASSES },
+    });
+    started.unref();
+    return started;
+}
+/** Checkpoints `dbPath` off the calling thread until `stop()`;
+ * the worker starts with the first checkpoint that is due. */
 export function startWalCheckpointer(dbPath) {
     const key = path.resolve(dbPath);
     let worker;
@@ -58,16 +71,15 @@ export function startWalCheckpointer(dbPath) {
         backgrounded.delete(key);
     };
     const spawn = () => {
-        // An explicit execArgv keeps the parent's loaders out of the worker and silences its repeat of the node:sqlite warning.
-        const started = new Worker(WORKER_SOURCE, { eval: true, execArgv: ['--no-warnings'], workerData: { dbPath: key, maxPasses: MAX_PASSES } });
-        started.unref();
+        const started = newCheckpointWorker(key);
         started.on('message', (settled) => {
             running = false;
             due = settled ? RESPONSES_PER_CHECKPOINT : RESPONSES_PER_RETRY;
         });
         started.on('error', (err) => {
             end();
-            log.warn(`background checkpoint of ${key} stopped (${errorMessage(err)}); each connection checkpoints inside its own commit again`);
+            log.warn(`background checkpoint of ${key} stopped (${errorMessage(err)}); ` +
+                `each connection checkpoints inside its own commit again`, errorFields(err));
         });
         exited = new Promise((resolve) => { started.once('exit', () => resolve()); });
         return started;

package/dist/doctor.d.ts

@@ -1,3 +1,4 @@
+import { type SpoolFs } from './capture/compaction-spool.js';
 /** Outcome of one check. `fail` makes `hippo doctor` exit 1. */
 export type DoctorStatus = 'pass' | 'warn' | 'fail' | 'info';
 /** One check in a {@link DoctorReport}. */
@@ -19,11 +20,16 @@ export interface DoctorReport {
 /** Inputs for {@link runDoctor}; defaults come from the process. */
 export interface DoctorOpts {
     cwd?: string;
-    /** Home directory used to find agent configuration (~/.claude unless CLAUDE_CONFIG_DIR is set, ~/.codex unless CODEX_HOME is). */
+    /**
+     * Home directory used to find agent configuration (~/.claude unless CLAUDE_CONFIG_DIR is set, ~/.codex unless
+     * CODEX_HOME is).
+     */
     home?: string;
     version: string;
     nodeVersion?: string;
     now?: Date;
+    /** Stands in for the fs the spool check reads; a test makes one call fail. */
+    spoolFs?: SpoolFs;
 }
 /** Minimum Node.js version hippo supports (package.json engines). */
 export declare const MIN_NODE = "22.16.0";