hippo-memory 1.59.0 → 1.61.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',
@@ -252,6 +253,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 +264,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;
@@ -205,6 +208,7 @@ export function createDeliveryRecorder(init) {
                 return;
             flushed = true;
             if (broken !== null) {
+                // Same pinned `[hippo] delivery ledger` hook stderr line as recall-trace.ts's write failure.
                 console.error(`[hippo] delivery ledger skipped: recorder failed: ${broken}`);
                 return;
             }

package/dist/doctor.js

@@ -9,12 +9,12 @@ 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 { isEmbeddingAvailable } from './local-embedding.js';
+import { CODEX_TRUST_LINE, codexHomeDir, isCodexPresent, isJsonObject } from './hooks/shared.js';
 import { planUserGlobalRepair } from './project-merge.js';
 import { resolveTenantId } from './tenant.js';
 /** Minimum Node.js version hippo supports (package.json engines). */
@@ -36,6 +36,7 @@ function readJson(file) {
         return JSON.parse(fs.readFileSync(file, 'utf8'));
     }
     catch {
+        // A missing or corrupt file is the finding doctor reports, so null is the answer.
         return null;
     }
 }

package/dist/dormant.js

@@ -36,6 +36,7 @@ function parseSnapshot(row) {
         return entry;
     }
     catch {
+        // A row that will not parse is out of shape, so it is not restorable.
         return null;
     }
 }

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,9 +30,10 @@
  * `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 { redactSecrets } from './secret-detect.js';
+import { redactSecretsStrict } from './secret-detect.js';
 import { fetchWithRetry } from './http-retry.js';
 export const API_PROVIDER_KINDS = ['openai', 'voyage', 'cohere'];
 function isApiProviderKind(x) {
@@ -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. ` +
@@ -191,7 +192,7 @@ class ApiEmbeddingProvider {
                     'content-type': 'application/json',
                     authorization: `Bearer ${key}`,
                 },
-                body: JSON.stringify(spec.buildBody(this.model, chunk.map(redactSecrets), role)),
+                body: JSON.stringify(spec.buildBody(this.model, chunk.map(redactSecretsStrict), role)),
             }, { timeoutMs: REQUEST_TIMEOUT_MS });
         }
         catch (err) {
@@ -237,6 +238,7 @@ function readEmbeddingsConfig(hippoRoot) {
         return loadConfig(hippoRoot).embeddings;
     }
     catch {
+        // An unreadable config falls back to provider defaults; loadConfig warns on a bad parse.
         return {};
     }
 }

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.
  */