hippo-memory 1.60.0 → 1.62.0

package/dist/decisions.d.ts

@@ -20,9 +20,10 @@
  *
  * Dual-write atomicity: `saveDecision` writes the memory + decisions row (and,
  * when superseding, the old row's UPDATE) inside writeEntry's SAVEPOINT
- * 'write_entry' (store.ts:1196) via the afterWrite hook, so a failure in any
+ * 'write_entry' (store/entry-writes.ts) via the afterWrite hook, so a failure in any
  * step rolls all of them back. Pattern matches savePrediction (predictions.ts).
  */
+import { type KeysetPosition } from './keyset.js';
 export type DecisionStatus = 'active' | 'superseded' | 'closed';
 export declare const VALID_DECISION_STATES: ReadonlySet<DecisionStatus>;
 export interface Decision {
@@ -54,6 +55,8 @@ export interface SaveDecisionOpts {
 export interface ListDecisionsOpts {
     status?: DecisionStatus;
     limit?: number;
+    /** Resume after this row: the position the previous page ended on. */
+    after?: KeysetPosition;
 }
 /**
  * Create a decision. Writes the memory mirror + the decisions row atomically

package/dist/decisions.js

@@ -20,17 +20,18 @@
  *
  * Dual-write atomicity: `saveDecision` writes the memory + decisions row (and,
  * when superseding, the old row's UPDATE) inside writeEntry's SAVEPOINT
- * 'write_entry' (store.ts:1196) via the afterWrite hook, so a failure in any
+ * 'write_entry' (store/entry-writes.ts) via the afterWrite hook, so a failure in any
  * step rolls all of them back. Pattern matches savePrediction (predictions.ts).
  */
 import { BadRequestError, ConflictError, NotFoundError } from './api-errors.js';
 import { openHippoDb, closeHippoDb } from './db.js';
-import { writeEntry } from './store.js';
+import { writeEntry } from './store/entry-writes.js';
 import { assertTenantId } from './tenant.js';
-import { markGraphDirty, removeGraphEntitiesForObject } from './graph.js';
+import { markGraphDirty, removeGraphEntitiesForObject } from './graph/write.js';
 import { createMemory, Layer } from './memory.js';
 import { appendAuditEvent } from './audit.js';
 import { objectHalfLifeDays } from './half-life-migration.js';
+import { keysetAfter } from './keyset.js';
 export const VALID_DECISION_STATES = new Set([
     'active',
     'superseded',
@@ -59,6 +60,97 @@ const DECISION_COLS = `
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
+/** The legacy `hippo decide` memory mirror for a decision. */
+function buildDecisionMemory(hippoRoot, tenantId, opts) {
+    const content = opts.context
+        ? `${opts.decisionText}\n\nContext: ${opts.context}`
+        : opts.decisionText;
+    const tags = ['decision', ...(opts.extraTags ?? [])];
+    return createMemory(content, {
+        tags,
+        layer: Layer.Semantic,
+        confidence: 'verified',
+        source: 'decision',
+        baseHalfLifeDays: objectHalfLifeDays(hippoRoot),
+        tenantId,
+    });
+}
+// Preflight the supersede target BEFORE inserting the new row. The new
+// row's autoincrement id could otherwise collide with a non-existent
+// supersedesDecisionId (e.g. superseding id 1 on an empty store, where the
+// INSERT below would itself become id 1), making the row supersede itself.
+// Validating first means the new row is never a candidate for its own
+// supersede UPDATE. codex review 2026-05-28 (P1).
+function preflightDecisionSupersede(db, tenantId, supersedesId) {
+    // SAFETY: row shape matches the single `status` column named in the SELECT below.
+    const pred = db.prepare(`SELECT status FROM decisions WHERE id = ? AND tenant_id = ?`).get(supersedesId, tenantId);
+    if (!pred) {
+        throw new NotFoundError(`saveDecision: decision ${supersedesId} to supersede not found for tenant ${tenantId}`);
+    }
+    if (pred.status !== 'active') {
+        throw new ConflictError(`saveDecision: decision ${supersedesId} is not active (status='${pred.status}'); only active decisions can be superseded.`);
+    }
+}
+function insertDecisionRow(db, memoryId, tenantId, opts, now) {
+    const result = db.prepare(`
+    INSERT INTO decisions(
+      memory_id, tenant_id, decision_text, context,
+      status, superseded_by, superseded_at, closed_at, created_at
+    ) VALUES (?, ?, ?, ?, 'active', NULL, NULL, NULL, ?)
+  `).run(memoryId, tenantId, opts.decisionText, opts.context ?? null, now);
+    return Number(result.lastInsertRowid ?? 0);
+}
+// Supersede the (preflight-validated) prior active decision in the SAME
+// SAVEPOINT, atomic with the new row. The `id != decisionId` exclusion is
+// defense-in-depth against the self-match described above; combined with
+// the preflight, a 0-change here is unreachable in the single-writer txn.
+function supersedeDecisionRow(db, tenantId, actor, supersedesId, decisionId, now) {
+    const sup = db.prepare(`
+    UPDATE decisions
+    SET status = 'superseded', superseded_by = ?, superseded_at = ?
+    WHERE id = ? AND tenant_id = ? AND status = 'active' AND id != ?
+  `).run(decisionId, now, supersedesId, tenantId, decisionId);
+    if (sup.changes === 0) {
+        throw new BadRequestError(`saveDecision: decision ${supersedesId} could not be superseded (no longer active or self-reference).`);
+    }
+    appendAuditEvent(db, {
+        tenantId,
+        actor,
+        op: 'decision_supersede',
+        targetId: String(supersedesId),
+        metadata: {
+            decision_id: supersedesId,
+            superseded_by: decisionId,
+        },
+    });
+}
+/** The afterWrite body: preflight, INSERT, supersede, reload, create audit, all in one SAVEPOINT. */
+function writeDecisionRow(db, memoryId, tenantId, opts, actor, now) {
+    if (opts.supersedesDecisionId !== undefined) {
+        preflightDecisionSupersede(db, tenantId, opts.supersedesDecisionId);
+    }
+    const decisionId = insertDecisionRow(db, memoryId, tenantId, opts, now);
+    if (opts.supersedesDecisionId !== undefined) {
+        supersedeDecisionRow(db, tenantId, actor, opts.supersedesDecisionId, decisionId, now);
+    }
+    // SAFETY: row's shape matches the columns named in DECISION_COLS above.
+    const row = db.prepare(`SELECT ${DECISION_COLS} FROM decisions WHERE id = ?`)
+        .get(decisionId);
+    if (!row)
+        throw new Error('saveDecision: failed to reload saved decision row');
+    // GDPR-light metadata: id + flag only, no decision_text.
+    appendAuditEvent(db, {
+        tenantId,
+        actor,
+        op: 'decision_create',
+        targetId: String(decisionId),
+        metadata: {
+            decision_id: decisionId,
+            has_context: opts.context !== undefined && opts.context !== null && opts.context !== '',
+        },
+    });
+    return row;
+}
 /**
  * Create a decision. Writes the memory mirror + the decisions row atomically
  * inside writeEntry's SAVEPOINT 'write_entry'. When supersedesDecisionId is
@@ -76,88 +168,14 @@ export function saveDecision(hippoRoot, tenantId, opts, actor = 'cli') {
     if (!opts.decisionText)
         throw new BadRequestError('saveDecision: decisionText is required');
     const now = new Date().toISOString();
-    const content = opts.context
-        ? `${opts.decisionText}\n\nContext: ${opts.context}`
-        : opts.decisionText;
-    const tags = ['decision', ...(opts.extraTags ?? [])];
-    const mem = createMemory(content, {
-        tags,
-        layer: Layer.Semantic,
-        confidence: 'verified',
-        source: 'decision',
-        baseHalfLifeDays: objectHalfLifeDays(hippoRoot),
-        tenantId,
-    });
+    const mem = buildDecisionMemory(hippoRoot, tenantId, opts);
     // Populated inside afterWrite so the INSERT, the supersede UPDATE, and the
     // memory write all share one SAVEPOINT.
     let savedRow;
     writeEntry(hippoRoot, mem, {
         actor,
         afterWrite: (db, memoryId) => {
-            // Preflight the supersede target BEFORE inserting the new row. The new
-            // row's autoincrement id could otherwise collide with a non-existent
-            // supersedesDecisionId (e.g. superseding id 1 on an empty store, where the
-            // INSERT below would itself become id 1), making the row supersede itself.
-            // Validating first means the new row is never a candidate for its own
-            // supersede UPDATE. codex review 2026-05-28 (P1).
-            if (opts.supersedesDecisionId !== undefined) {
-                // SAFETY: row shape matches the single `status` column named in the SELECT below.
-                const pred = db.prepare(`SELECT status FROM decisions WHERE id = ? AND tenant_id = ?`).get(opts.supersedesDecisionId, tenantId);
-                if (!pred) {
-                    throw new NotFoundError(`saveDecision: decision ${opts.supersedesDecisionId} to supersede not found for tenant ${tenantId}`);
-                }
-                if (pred.status !== 'active') {
-                    throw new ConflictError(`saveDecision: decision ${opts.supersedesDecisionId} is not active (status='${pred.status}'); only active decisions can be superseded.`);
-                }
-            }
-            const result = db.prepare(`
-        INSERT INTO decisions(
-          memory_id, tenant_id, decision_text, context,
-          status, superseded_by, superseded_at, closed_at, created_at
-        ) VALUES (?, ?, ?, ?, 'active', NULL, NULL, NULL, ?)
-      `).run(memoryId, tenantId, opts.decisionText, opts.context ?? null, now);
-            const decisionId = Number(result.lastInsertRowid ?? 0);
-            // Supersede the (preflight-validated) prior active decision in the SAME
-            // SAVEPOINT, atomic with the new row. The `id != decisionId` exclusion is
-            // defense-in-depth against the self-match described above; combined with
-            // the preflight, a 0-change here is unreachable in the single-writer txn.
-            if (opts.supersedesDecisionId !== undefined) {
-                const sup = db.prepare(`
-          UPDATE decisions
-          SET status = 'superseded', superseded_by = ?, superseded_at = ?
-          WHERE id = ? AND tenant_id = ? AND status = 'active' AND id != ?
-        `).run(decisionId, now, opts.supersedesDecisionId, tenantId, decisionId);
-                if (sup.changes === 0) {
-                    throw new BadRequestError(`saveDecision: decision ${opts.supersedesDecisionId} could not be superseded (no longer active or self-reference).`);
-                }
-                appendAuditEvent(db, {
-                    tenantId,
-                    actor,
-                    op: 'decision_supersede',
-                    targetId: String(opts.supersedesDecisionId),
-                    metadata: {
-                        decision_id: opts.supersedesDecisionId,
-                        superseded_by: decisionId,
-                    },
-                });
-            }
-            // SAFETY: row's shape matches the columns named in DECISION_COLS above.
-            const row = db.prepare(`SELECT ${DECISION_COLS} FROM decisions WHERE id = ?`)
-                .get(decisionId);
-            if (!row)
-                throw new Error('saveDecision: failed to reload saved decision row');
-            savedRow = row;
-            // GDPR-light metadata: id + flag only, no decision_text.
-            appendAuditEvent(db, {
-                tenantId,
-                actor,
-                op: 'decision_create',
-                targetId: String(decisionId),
-                metadata: {
-                    decision_id: decisionId,
-                    has_context: opts.context !== undefined && opts.context !== null && opts.context !== '',
-                },
-            });
+            savedRow = writeDecisionRow(db, memoryId, tenantId, opts, actor, now);
         },
         // Post-commit hook: mark the tenant's graph dirty AFTER the DB row commits
         // but BEFORE the markdown mirrors are written, so a mirror-write failure can
@@ -252,6 +270,7 @@ export function loadDecisionById(hippoRoot, tenantId, id) {
 export function loadDecisions(hippoRoot, tenantId, opts = {}) {
     assertTenantId('loadDecisions', tenantId);
     const limit = opts.limit ?? 100;
+    const after = keysetAfter('created_at', 'id', opts.after);
     const db = openHippoDb(hippoRoot);
     try {
         let rows;
@@ -262,19 +281,19 @@ export function loadDecisions(hippoRoot, tenantId, opts = {}) {
             // SAFETY: rows' shape matches the columns named in DECISION_COLS above.
             rows = db.prepare(`
         SELECT ${DECISION_COLS} FROM decisions
-        WHERE tenant_id = ? AND status = ?
+        WHERE tenant_id = ? AND status = ?${after.sql}
         ORDER BY created_at DESC, id DESC
         LIMIT ?
-      `).all(tenantId, opts.status, limit);
+      `).all(tenantId, opts.status, ...after.params, limit);
         }
         else {
             // SAFETY: rows' shape matches the columns named in DECISION_COLS above.
             rows = db.prepare(`
         SELECT ${DECISION_COLS} FROM decisions
-        WHERE tenant_id = ?
+        WHERE tenant_id = ?${after.sql}
         ORDER BY created_at DESC, id DESC
         LIMIT ?
-      `).all(tenantId, limit);
+      `).all(tenantId, ...after.params, limit);
         }
         return rows.map(rowToDecision);
     }

package/dist/dedupe.js

@@ -20,8 +20,9 @@
  * WITHIN each tenant group; cross-tenant pairs are never compared. Raw and
  * superseded rows are not candidates at all (v1.38.1).
  */
-import { textOverlap } from './search.js';
-import { loadAllEntries, deleteEntry, memoriesBackingObjects } from './store.js';
+import { textOverlap } from './tokenize.js';
+import { loadAllEntries } from './store/entry-reads.js';
+import { deleteEntry, memoriesBackingObjects } from './store/delete-and-batch.js';
 import { compareEntryIdentity } from './compare.js';
 import { canAutoDelete } from './memory.js';
 import { derivationPartitionKey } from './recall-scope.js';

package/dist/delivery-recorder.js

@@ -1,3 +1,6 @@
+// In-memory observer for one pinned-only context call: what was considered, why each was rejected, what reached stdout.
+// No DB access (the caller hands build()'s output to src/recall-trace.ts); hashes, ids, counts and enums only, never text.
+import { envTestDeliveryFault } from './env.js';
 import { evalNow } from './ablation.js';
 import { scoreOverlap } from './prompt-recall.js';
 import { blockHash, estimateTokens, hookPayloadSessionId, hookPayloadString, isSubagentPayload } from './token-ledger.js';
@@ -26,7 +29,7 @@ export function createDeliveryRecorder(init) {
     const startedMs = Date.now();
     const ts = evalNow().toISOString();
     // Test-only fault injection, as HIPPO_FAKE_NOW is for time.
-    const fault = process.env.HIPPO_TEST_DELIVERY_FAULT ?? '';
+    const fault = envTestDeliveryFault();
     const payloadSession = hookPayloadSessionId(init.stdinText);
     const subagent = isSubagentPayload(init.stdinText);
     const envSession = init.envSessionId !== undefined && init.envSessionId !== '' ? init.envSessionId : null;

package/dist/doctor.js

@@ -9,13 +9,13 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { findHippoStoreDir } from './project-identity.js';
 import { getGlobalRoot } from './shared.js';
-import { isInitialized } from './store.js';
+import { isInitialized } from './store/open.js';
 import { loadConfig } from './config.js';
 import { openHippoDbReadOnly, closeHippoDb, getSchemaVersion, getCurrentSchemaVersion, countTableRows, IncompatibleBinaryError } from './db.js';
 import { REPLAY_AFTER_MS, TRANSCRIPT_FILL_WINDOW_MS } from './compaction-record.js';
-import { isEmbeddingAvailable } from './embeddings.js';
-import { CODEX_TRUST_LINE, codexHomeDir, isCodexPresent, isJsonObject } from './hooks.js';
-import { planUserGlobalRepair } from './project-merge.js';
+import { isEmbeddingAvailable } from './local-embedding.js';
+import { CODEX_TRUST_LINE, codexHomeDir, isCodexPresent, isJsonObject } from './hooks/shared.js';
+import { planProjectRepair } from './project-merge.js';
 import { resolveTenantId } from './tenant.js';
 /** Minimum Node.js version hippo supports (package.json engines). */
 export const MIN_NODE = '22.16.0';
@@ -131,16 +131,20 @@ function compactionsCheck(db, now) {
             : { id: 'compactions', status: 'warn', detail: `cannot read the compaction records: ${message}` };
     }
 }
-/** Merged rows older sleep saved as user-global, counted by the repair's own dry run so a truly user-global merge never warns. */
+/** Old project tags in the global store, counted by the repair's own plan so a truly user-global merge never warns. */
 function projectsCheck(globalRoot) {
     let db = null;
     try {
         db = openHippoDbReadOnly(globalRoot);
-        const r = planUserGlobalRepair(db, resolveTenantId({}));
-        const n = r.toProject.length + r.setAside.length;
-        return n === 0
-            ? { id: 'projects', status: 'pass', detail: 'no merged memories in the global store are tagged user-global by mistake' }
-            : { id: 'projects', status: 'warn', detail: `${n} merged memories in the global store are tagged user-global, so every project's context can show them`, fix: 'hippo projects repair --global   (dry run; add --apply to write)' };
+        const r = planProjectRepair(db, globalRoot, resolveTenantId({}));
+        const found = [
+            r.copies.length > 0 ? `${r.copies.length} imported notes copied under the wrong project` : '',
+            r.folds.length > 0 ? `${r.folds.length} old project names that now resolve to another project` : '',
+            r.toProject.length + r.setAside.length > 0 ? `${r.toProject.length + r.setAside.length} merged memories tagged user-global` : '',
+        ].filter((s) => s !== '');
+        return found.length === 0
+            ? { id: 'projects', status: 'pass', detail: 'no duplicate or out-of-date project tags in the global store' }
+            : { id: 'projects', status: 'warn', detail: `global store: ${found.join('; ')}`, fix: 'hippo projects repair --global   (dry run; add --apply to write)' };
     }
     catch (err) {
         return { id: 'projects', status: 'info', detail: `project tags not checked (${err instanceof Error ? err.message : String(err)})` };

package/dist/embedding-provider.d.ts

@@ -30,7 +30,7 @@
  * `fetch` and are integration-verified in Workstream C (real API calls are
  * egress-blocked in the build sandbox).
  */
-import { type EmbeddingRole } from './embeddings.js';
+import { type EmbeddingRole } from './local-embedding.js';
 export type EmbeddingProviderKind = 'local' | 'openai' | 'voyage' | 'cohere';
 export declare const API_PROVIDER_KINDS: readonly EmbeddingProviderKind[];
 export interface EmbeddingProvider {

package/dist/embedding-provider.js

@@ -30,7 +30,8 @@
  * `fetch` and are integration-verified in Workstream C (real API calls are
  * egress-blocked in the build sandbox).
  */
-import { getEmbedding, isEmbeddingAvailable, resolveEmbeddingModel, DEFAULT_EMBEDDING_MODEL, } from './embeddings.js';
+import { envByName } from './env.js';
+import { getEmbedding, isEmbeddingAvailable, resolveEmbeddingModel, DEFAULT_EMBEDDING_MODEL, } from './local-embedding.js';
 import { loadConfig } from './config.js';
 import { redactSecretsStrict } from './secret-detect.js';
 import { fetchWithRetry } from './http-retry.js';
@@ -160,12 +161,12 @@ class ApiEmbeddingProvider {
         return API_PROVIDER_SPECS[this.kind].keyEnv;
     }
     isAvailable() {
-        return this.enabled && !!process.env[this.keyEnv]?.trim();
+        return this.enabled && !!envByName(this.keyEnv)?.trim();
     }
     async embed(texts, role) {
         if (texts.length === 0)
             return [];
-        const key = process.env[this.keyEnv]?.trim();
+        const key = envByName(this.keyEnv)?.trim();
         if (!key) {
             // Hard, actionable failure — never includes a key value (there is none).
             throw new Error(`Embedding provider '${this.kind}' is configured but ${this.keyEnv} is not set. ` +

package/dist/embeddings.d.ts

@@ -4,9 +4,9 @@
  * Falls back silently if the library is not installed.
  */
 import { MemoryEntry } from './memory.js';
+import { EMBEDDING_MODEL_META_KEY } from './vector-store.js';
 import { type EmbeddingProvider } from './embedding-provider.js';
-export declare const DEFAULT_EMBEDDING_MODEL = "Xenova/all-MiniLM-L6-v2";
-export declare const EMBEDDING_MODEL_META_KEY = "embedding_model";
+export { EMBEDDING_MODEL_META_KEY };
 /**
  * Bump whenever `embeddingInputText`'s composition changes in a way that
  * changes the resulting vectors for existing entries. Folded into the stored
@@ -57,39 +57,6 @@ export declare function embeddingInputText(entry: {
     content: string;
     tags: string[];
 }): string;
-/**
- * Per-model pooling dispatch for Transformers.js's feature-extraction
- * pipeline. BGE family models were trained with CLS pooling (per BAAI's
- * official inference code in `FlagEmbedding`); MiniLM and most sentence-
- * transformers models use mean pooling. Unknown model ids default to mean
- * — that is the safe choice because most third-party models adopt the
- * sentence-transformers convention, and the alternative ('cls') silently
- * degrades vector quality for mean-pooling models.
- */
-export declare function poolingFor(model: string): 'cls' | 'mean';
-/**
- * Per-model input-prefix dispatch. The intfloat/e5 family was trained with
- * asymmetric "query: " / "passage: " prefixes — the model only matches the
- * two halves correctly when each side carries its prefix at inference. BGE
- * also has prefix conventions for some downstream tasks, but symmetric use
- * without prefixes is the documented default for `bge-*-en-v1.5`, so we leave
- * BGE alone here. Symmetric models (MiniLM, BGE) and unknown models return
- * an empty prefix.
- *
- * `role` semantics:
- *   - 'query'   — the text is the user's question / search input.
- *   - 'passage' — the text is a document being indexed.
- *   - undefined or absent — symmetric path; no prefix is applied even for
- *     asymmetric models (preserves backwards compatibility with the legacy
- *     two-argument `getEmbedding(text, model)` API).
- */
-export type EmbeddingRole = 'query' | 'passage';
-export declare function prefixFor(model: string, role?: EmbeddingRole): string;
-/**
- * Check (synchronously) if @xenova/transformers or @huggingface/transformers is installed.
- */
-export declare function isEmbeddingAvailable(): boolean;
-export declare function resolveEmbeddingModel(hippoRoot: string, explicitModel?: string): string;
 /**
  * Persist the stored-index identity for `model` (see `embeddingIndexIdentity`).
  * Versioning happens INSIDE this function, not at call sites, so every caller
@@ -99,29 +66,19 @@ export declare function resolveEmbeddingModel(hippoRoot: string, explicitModel?:
 export declare function saveStoredEmbeddingModel(hippoRoot: string, model: string): void;
 export declare function resolveIndexedEmbeddingModel(hippoRoot: string, index?: Record<string, number[]>): string | null;
 export declare function embeddingModelRequiresReindex(hippoRoot: string, model: string, index?: Record<string, number[]>): boolean;
-/**
- * Get an embedding vector for a piece of text.
- * Returns an empty array if transformers is not available or fails.
- *
- * Pass `role: 'query'` / `'passage'` to engage asymmetric prefixing for
- * model families that require it (currently intfloat/e5-*). Omitting `role`
- * keeps the legacy symmetric behavior (no prefix), so BGE / MiniLM callers
- * don't need to change.
- */
-export declare function getEmbedding(text: string, model?: string, role?: EmbeddingRole): Promise<number[]>;
 /**
  * Cosine similarity between two vectors. Handles unnormalized vectors.
  * Returns 0 for empty or mismatched vectors.
  */
 export declare function cosineSimilarity(a: number[], b: number[]): number;
-/**
- * Load the cached embedding index; `{}` when the file is missing. A corrupt file is moved aside and rebuilt on the next embed; any other read error throws, so nothing saves over an index it could not read.
- */
+/** 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[]>;
-/**
- * Save the embedding index to disk.
- */
-export declare function saveEmbeddingIndex(hippoRoot: string, index: Record<string, number[]>): void;
+/** Stored vectors for `ids` only. */
+export declare function loadStoredVectors(hippoRoot: string, ids: readonly string[]): Map<string, number[]>;
+/** Whether the store holds any vector at all. */
+export declare function hasEmbeddings(hippoRoot: string): boolean;
+/** 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;
 /**
  * Embed a single memory entry and cache the result in the embedding index.
  */