hippo-memory 1.70.0 → 1.72.0

package/dist/store/dormant.js

@@ -1,24 +1,10 @@
-/**
- * Dormant memories: what sleep does with a faded memory instead of deleting
- * it (config `dormant.enabled`, on by default; `retentionDays` bounds how
- * long one is kept).
- *
- * A dormant memory keeps its full content in `dormant_memories` (schema v44)
- * but is no longer a `memories` row, so recall, context, every sleep pass and
- * every other reader of `memories` stop seeing it exactly as if it had been
- * deleted. `hippo dormant` lists and searches them, `hippo dormant restore`
- * brings one back, `hippo dormant forget` deletes one for good.
- *
- * Not to be confused with the raw archive (`raw_archive`, `archiveRawMemory`,
- * `hippo forget --archive`): that path removes a raw receipt's content and
- * keeps only its metadata. A dormant memory keeps its content.
- *
- * The db-taking helpers leave the handle and any transaction to the caller.
- * The hippoRoot-taking functions at the end open one of their own, for
- * api.listDormant / restoreDormant / forgetDormant / isDormant.
- */
+/** Dormant memories: what sleep does with a faded memory instead of deleting it (config `dormant.enabled`; `retentionDays` bounds how long one is kept).
+ * Content stays in `dormant_memories` (schema v44) and the `memories` row goes, so every reader of `memories` stops seeing it, as if deleted.
+ * Not the raw archive (`raw_archive`, `archiveRawMemory`), which keeps metadata only. db-taking helpers leave the handle and transaction to the caller. */
 import { closeHippoDb, openHippoDb, withWriteScope, withWriteScopeOr } from '../db/index.js';
-import { RejectedValueError, rejectionDigest } from './rejection.js';
+import { onHandle } from './open.js';
+import { rejectionDigest } from './rejection.js';
+import { RejectedValueError } from '../core/api-errors.js';
 import { escapeLike } from '../util/escape.js';
 import { warnDamagedColumn } from '../util/stored-json.js';
 import { DAY_MS } from '../util/time.js';
@@ -27,11 +13,7 @@ import { audit, auditRejectionRefusal } from './audit-event.js';
 import { entryIdTakenAt } from './entry-reads.js';
 import { writeEntryDbOnly, writeEntryMirrors } from './entry-writes.js';
 const DEFAULT_LIST_LIMIT = 20;
-/**
- * Insert (or refresh) the dormant snapshot for `move.entry`. Does not touch
- * the `memories` row: the caller deletes it in the same transaction, so the
- * memory is never in both places or in neither.
- */
+/** Insert (or refresh) the dormant snapshot for `move.entry`; the caller deletes the `memories` row in the same transaction. */
 export function insertDormantRow(db, move) {
     db.prepare(`
     INSERT INTO dormant_memories (tenant_id, id, content, entry_json, reason, strength, dormant_at)
@@ -44,16 +26,14 @@ export function insertDormantRow(db, move) {
       dormant_at = excluded.dormant_at
   `).run(move.entry.tenantId, move.entry.id, move.entry.content, JSON.stringify(move.entry), move.reason, move.strength, move.dormantAt);
 }
-/**
- * Parse a stored snapshot back into a MemoryEntry, or null when the row no
- * longer matches the snapshot it carries (edited by hand, or truncated).
- */
+/** Parse a stored snapshot back into a MemoryEntry, or null when the row no longer matches it (edited by hand, or truncated). */
 function parseSnapshot(row) {
     try {
         // SAFETY: entry_json is only written by insertDormantRow from a MemoryEntry;
         // the id / tenant / content checks below reject a row edited out of shape.
         const entry = JSON.parse(row.entry_json);
         if (entry.id !== row.id || entry.tenantId !== row.tenant_id || entry.content !== row.content) {
+            warnDamagedColumn({ table: 'dormant_memories', id: row.id, column: 'entry_json' }, 'wrong shape');
             return null;
         }
         return entry;
@@ -94,10 +74,7 @@ function listDormantRows(db, tenantId, opts = {}, admit = EVERY_SCOPE) {
       LIMIT ?`).all(tenantId, ...admit.params, ...terms.map((t) => `%${escapeLike(t)}%`), limit);
     return rows.map(rowToDormantMemory);
 }
-/**
- * The stored snapshot for a tenant's dormant memory, or null when the tenant
- * has no dormant memory with that id (another tenant's id reads as absent).
- */
+/** A tenant's stored dormant snapshot, or null when it has none with that id (another tenant's id reads as absent). */
 export function readDormantSnapshot(db, tenantId, id) {
     // SAFETY: row's shape matches the seven columns named in the SELECT.
     const row = db.prepare(`SELECT tenant_id, id, content, entry_json, reason, strength, dormant_at
@@ -193,23 +170,15 @@ export async function expireDormantBefore(hippoRoot, cutoffIso, opts) {
 }
 /** A tenant's dormant memories whose scope `admit` passes, newest first, read on a handle of its own. */
 export function loadDormantMemories(hippoRoot, tenantId, opts = {}, admit = EVERY_SCOPE) {
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return listDormantRows(db, tenantId, opts, admit);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 /** Whether a tenant holds a dormant memory with this id whose scope `admit` passes, read on a handle of its own. */
 export function holdsDormantMemory(hippoRoot, tenantId, id, admit = EVERY_SCOPE) {
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         return hasDormantRow(db, tenantId, id, admit);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 function auditDormantRestore(db, restore, snapshot, now) {
     appendAuditEvent(db, {
@@ -244,8 +213,7 @@ function restoreInWriteScope(db, restore) {
 }
 /** Brings one dormant memory back on a single handle: the live row, the dormant delete and the audit row commit together, then its mirrors are written. */
 export function restoreDormantMemory(hippoRoot, restore) {
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         let outcome;
         try {
             outcome = restoreInWriteScope(db, restore);
@@ -259,24 +227,17 @@ export function restoreDormantMemory(hippoRoot, restore) {
         if (outcome.status === 'restored')
             writeEntryMirrors(hippoRoot, outcome.entry);
         return outcome;
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 /** Deletes a tenant's dormant memory for good and writes its `forget` audit row, on a single handle; false when it holds none `admit` passes. */
 export function forgetDormantMemory(hippoRoot, forget) {
     const { tenantId, id, actor, admit } = forget;
-    const db = openHippoDb(hippoRoot);
-    try {
+    return onHandle(hippoRoot, (db) => {
         if (!hasDormantRow(db, tenantId, id, admit) || !deleteDormantRow(db, tenantId, id))
             return false;
         // Best-effort, like every other forget audit row: the delete stands.
         audit(db, 'forget', { tenantId, actor, targetId: id, metadata: { dormant: true } });
         return true;
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    });
 }
 //# sourceMappingURL=dormant.js.map

package/dist/store/embeddings/index.d.ts

@@ -1,105 +1,26 @@
-/**
- * Optional embedding-based semantic search for Hippo.
- * Uses @huggingface/transformers (local, zero API keys, ~22MB model).
- * Falls back silently if the library is not installed.
- */
-import { MemoryEntry } from '../../core/memory.js';
-import { type DatabaseSyncLike } from '../../db/index.js';
+/** The stored vector index's identity: which model and text format built it, and when a provider change means a rebuild.
+ * Picking a provider and computing vectors sit in src/search/embed-memories.ts; this module only reads and writes what is stored. */
 import { EMBEDDING_MODEL_META_KEY } from '../../db/vector-store.js';
-import { type EmbeddingProvider } from './provider.js';
-import type { HippoStore } from '../index.js';
 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
- * index identity (see `embeddingIndexIdentity`) so a text-format change is
- * treated exactly like an embedding-model change: the next embed-touching
- * operation detects the mismatch and reindexes automatically. Format 2 =
- * `path:*` tags excluded (see `embeddingInputText`); format 1 (implicit, no
- * suffix) = `${content} ${tags.join(' ')}` including path tags.
- */
+/** Bump when `embeddingInputText` changes existing vectors; folded into the stored index identity (`embeddingIndexIdentity`) so it reindexes like a model
+ * change. Format 2 = `path:*` tags excluded; format 1 (implicit, no suffix) included them. */
 export declare const EMBED_TEXT_FORMAT = 2;
-/**
- * The stored-index identity for a given embedding provider id: folds
- * `EMBED_TEXT_FORMAT` into the provider id so index-identity comparisons
- * automatically invalidate on either a model change OR a text-format change.
- * This is the ONE choke point both `embeddingModelRequiresReindex` (compare
- * side) and `saveStoredEmbeddingModel` (save side) go through — they MUST
- * version identically, or every call reindexes in a loop (or none ever do).
- */
+/** Stored-index identity for a provider id: folds `EMBED_TEXT_FORMAT` in so a model or text-format change invalidates the index. The ONE choke point for
+ * compare (`embeddingModelRequiresReindex`) and save (`saveStoredEmbeddingModel`); they MUST version identically or every call reindexes. */
 export declare function embeddingIndexIdentity(providerId: string): string;
-/**
- * Build the text embedded for a memory entry: content plus its tags, joined
- * by a space and trimmed — the same shape as the legacy
- * `` `${e.content} ${e.tags.join(' ')}`.trim() `` composition, minus `path:*`
- * tags.
- *
- * `path:*` tags are excluded because they are auto-derived from
- * `process.cwd()` (see `extractPathTags` in cli.ts) and carry every path
- * component of the store's location, INCLUDING the store directory name
- * itself. That means identical content embeds to a DIFFERENT vector
- * depending on WHERE the store happens to live — e.g. a fresh benchmark run
- * under `tempfile.mkdtemp()` gets a new directory name (hence new path
- * tokens, hence a new vector) every single run, even with byte-identical
- * content ingested in byte-identical order. This was diagnosed as the
- * DOMINANT root cause of cross-fresh-ingest recall-rank variance measured on
- * LoCoMo (mean evidence-recall@5 stdev 0.0175 across 4 fresh re-ingests of
- * identical data; see `benchmarks/LOCOMO_INVESTIGATION.md`, "Determinism
- * characterization"). It is a real product defect beyond benchmarks too:
- * retrieval semantics should not depend on a project directory's name.
- *
- * Only `path:*` is excluded. Other tags (`conv:`, `session:`, `speaker:`,
- * `dia:`, `error`, `scope:`, etc.) remain embedded — they carry semantic
- * meaning. Path relevance at recall time is already handled explicitly by
- * the v39 scope-isolation layer (`origin_project`, `pathOverlapScore`), so
- * embedding-level path tokens are redundant with a dedicated mechanism
- * rather than a feature.
- */
+/** Text embedded for an entry: content plus tags, space-joined and trimmed, minus `path:*` tags.
+ * `path:*` tags derive from cwd, so identical content would embed differently per store location; path relevance is handled by `pathOverlapScore`. */
 export declare function embeddingInputText(entry: {
     content: string;
     tags: string[];
 }): string;
-/**
- * Persist the stored-index identity for `model` (see `embeddingIndexIdentity`).
- * Versioning happens INSIDE this function, not at call sites, so every caller
- * — current and future — gets the identity format for free. Must stay
- * consistent with the compare side in `embeddingModelRequiresReindex`.
- */
+/** Persist the stored-index identity for `model` (see `embeddingIndexIdentity`); versioning happens here, not at call sites,
+ * and must stay consistent with the compare side in `embeddingModelRequiresReindex`. */
 export declare function saveStoredEmbeddingModel(hippoRoot: string, model: string): void;
-/** 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;
 /** The one rebuild rule every store applies to its indexed model. */
 export declare function indexNeedsRebuild(indexed: string | null, providerId: string): boolean;
-/** 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;
 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;
-/** hippo.db's index state, the meta row and the EXISTS on one handle. */
-export declare function embeddingIndexStateAt(hippoRoot: string): EmbeddingIndexState;
-export declare function embeddingIndexStateOn(db: DatabaseSyncLike): EmbeddingIndexState;
-/**
- * Cosine similarity between two vectors. Handles unnormalized vectors.
- * Returns 0 for empty or mismatched vectors.
- */
+/** Cosine similarity; handles unnormalized vectors, returns 0 for empty or mismatched vectors. */
 export declare function cosineSimilarity(a: number[], b: number[]): number;
-/** `cosineSimilarity` over any indexable vectors; a Float32 view reads the same doubles as its number[] copy, so the score is the same. */
-export declare function cosineOf(a: ArrayLike<number>, b: ArrayLike<number>): number;
-/** 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[]>;
-/** 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;
-/** Embed a single memory entry and cache the result in the embedding index; with `store`, through its vectorWrites, never opening hippo.db. */
-export declare function embedMemory(hippoRoot: string, entry: MemoryEntry, model?: string, store?: HippoStore): Promise<void>;
-/** Embeds every entry with no cached vector, prunes vectors of deleted memories, and returns how many it embedded; `provider` defaults to the
- *  configured one. With `store`, every tenant's memories with no vector for the provider's model go through its `vectorWrites`, never hippo.db. */
-export declare function embedAll(hippoRoot: string, model?: string, provider?: EmbeddingProvider, store?: HippoStore): Promise<number>;
 //# sourceMappingURL=index.d.ts.map