hippo-memory 1.70.0 → 1.72.0

package/dist/store/entry-writes.d.ts

@@ -6,26 +6,20 @@ export interface WriteEntryOptions {
     /** Runs after the row commits and before the mirrors, on an idle connection; keep it best-effort. */
     afterCommit?: () => void;
 }
+/** Write an entry to SQLite and refresh mirrors; `opts.afterWrite` runs in the same SAVEPOINT as the INSERT, so a throw rolls the row back.
+ * `opts.actor` defaults to 'cli'; the api layer passes the resolved actor so the audit log gets one row per write. */
 export declare function writeEntry(hippoRoot: string, entry: MemoryEntry, opts?: WriteEntryOptions): void;
-/** writeEntry for each of `entries` in one transaction, so all land or none; each keeps its audit row, and mirrors follow the commit. Returns how many were written. */
+/** writeEntry for each of `entries` in one transaction, so all land or none; each
+ * keeps its audit row, and mirrors follow the commit. Returns how many were written; an empty list opens no store. */
 export declare function writeEntriesTogether(hippoRoot: string, entries: readonly MemoryEntry[]): number;
-/** writeEntry for each of `entries` on one open store, so the open and its lock wait are paid once; each row commits alone, and none opens the store when the list is empty. */
-export declare function writeEntriesSeparately(hippoRoot: string, entries: readonly MemoryEntry[]): void;
-/** Adds `tag` to each of a tenant's rows that lacks it, in `ids` order, each read fresh on one open store and committed alone; an id the tenant does not hold is skipped. */
+/** Runs `fill` in one transaction; each `put` writes one entry and returns false when the store rejects its value,
+ * leaving that row's refusal audit and the rest of the batch. Mirrors follow the commit. Returns how many were written. */
+export declare function writeEntriesSkippingRejected(hippoRoot: string, fill: (put: (entry: MemoryEntry) => boolean) => void, actor?: string): number;
+/** Adds `tag` to each of a tenant's rows that lacks it, in `ids` order, each read fresh
+ * on one open store and committed alone; an id the tenant does not hold is skipped. */
 export declare function addTagToEntries(hippoRoot: string, tenantId: string, ids: readonly string[], tag: string): void;
-/**
- * DB-only write path. Caller owns the open `db` handle. Runs upsert +
- * afterWrite hook + audit row inside one withWriteScope. Caller
- * is responsible for opening `db`, optionally wrapping in a larger BEGIN/
- * COMMIT (e.g. supersede's BEGIN IMMEDIATE), closing `db`, AND calling
- * `writeEntryMirrors` after the larger tx commits — mirrors must run
- * post-commit so a rolled-back tx never leaves orphan markdown.
- *
- * Audit-order note: the audit row is emitted INSIDE the write scope, so audit
- * commits atomically with the row INSERT. A subsequent mirror failure cannot
- * leave a recorded audit entry without its corresponding DB row. This is a
- * documented hardening over the prior writeEntry-as-monolith ordering.
- */
+/** DB-only write path: upsert, afterWrite hook and audit row inside one withWriteScope; the caller owns `db` and must call `writeEntryMirrors` after any
+ * outer tx commits, so a rolled-back tx never leaves orphan markdown. The audit row commits atomically with the INSERT. */
 export declare function writeEntryDbOnly(db: DatabaseSyncLike, entry: MemoryEntry, opts?: {
     actor?: string;
     afterWrite?: (db: DatabaseSyncLike, memoryId: string) => void;
@@ -42,7 +36,7 @@ export interface StrengthenOptions {
 /** Strengthen what a read returned: update only the four retrieval columns on the live row, never a stale copy.
  *  Best effort: a failure logs and never fails the read. Returns the ids found in this store. */
 export declare function strengthenRetrieved(hippoRoot: string, ids: readonly string[], opts: StrengthenOptions): Set<string>;
-/** strengthenRetrieved on an open handle that holds no transaction, so a recall's last writes share one handle. */
+/** strengthenRetrieved on an open handle in its own write scope, a savepoint inside a caller's transaction, so a recall's last writes share one handle. */
 export declare function strengthenRetrievedInOwnTx(db: DatabaseSyncLike, ids: readonly string[], opts: StrengthenOptions): Set<string>;
 /** strengthenRetrieved on the caller's handle, inside the caller's transaction. Throws; the caller decides. */
 export declare function strengthenRetrievedOn(db: DatabaseSyncLike, ids: readonly string[], opts: StrengthenOptions): Set<string>;

package/dist/store/entry-writes.js

@@ -1,24 +1,27 @@
+import { strengthAblation } from '../core/ablation.js';
 import { markRetrieved } from '../core/memory.js';
-import { closeHippoDb, openHippoDb, rethrowIfSqliteBlocked, withWriteScope } from '../db/index.js';
-import { RejectedValueError } from './rejection.js';
+import { closeHippoDb, openHippoDb, withWriteScope } from '../db/index.js';
+import { rethrowIfSqliteBlocked } from '../util/sqlite-blocked.js';
+import { RejectedValueError } from '../core/api-errors.js';
 import { markSummaryDirtyInTx } from './summary-dirty.js';
 import { errorMessage, log } from '../util/log.js';
 import { auditRejectionRefusal, audit } from './audit-event.js';
 import { selectEntriesByIds } from './entry-reads.js';
 import { stampOriginProject, upsertEntryRow, syncFtsRow, deleteFtsRow } from './entry-row.js';
 import { mirrorBestEffort, writeMarkdownMirror } from './mirrors.js';
-import { openStore } from './open.js';
+import { onHandle, openStore } from './open.js';
+/** Write an entry to SQLite and refresh mirrors; `opts.afterWrite` runs in the same SAVEPOINT as the INSERT, so a throw rolls the row back.
+ * `opts.actor` defaults to 'cli'; the api layer passes the resolved actor so the audit log gets one row per write. */
 export function writeEntry(hippoRoot, entry, opts) {
-    const db = openStore(hippoRoot);
-    try {
+    onHandle(hippoRoot, (db) => {
         writeEntryOn(db, hippoRoot, entry, opts);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
-/** writeEntry for each of `entries` in one transaction, so all land or none; each keeps its audit row, and mirrors follow the commit. Returns how many were written. */
+/** writeEntry for each of `entries` in one transaction, so all land or none; each
+ * keeps its audit row, and mirrors follow the commit. Returns how many were written; an empty list opens no store. */
 export function writeEntriesTogether(hippoRoot, entries) {
+    if (entries.length === 0)
+        return 0;
     const stamped = entries.map((entry) => stampOriginProject(hippoRoot, entry));
     const db = openStore(hippoRoot);
     try {
@@ -40,23 +43,36 @@ export function writeEntriesTogether(hippoRoot, entries) {
     }
     return stamped.length;
 }
-/** writeEntry for each of `entries` on one open store, so the open and its lock wait are paid once; each row commits alone, and none opens the store when the list is empty. */
-export function writeEntriesSeparately(hippoRoot, entries) {
-    if (entries.length === 0)
-        return;
-    const db = openStore(hippoRoot);
-    try {
-        for (const entry of entries)
-            writeEntryOn(db, hippoRoot, entry);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+/** Runs `fill` in one transaction; each `put` writes one entry and returns false when the store rejects its value,
+ * leaving that row's refusal audit and the rest of the batch. Mirrors follow the commit. Returns how many were written. */
+export function writeEntriesSkippingRejected(hippoRoot, fill, actor = 'cli') {
+    const written = [];
+    onHandle(hippoRoot, (db) => {
+        withWriteScope(db, 'write_entries_skipping_rejected', () => {
+            fill((entry) => {
+                const stamped = stampOriginProject(hippoRoot, entry);
+                try {
+                    writeEntryDbOnly(db, stamped, { actor });
+                }
+                catch (error) {
+                    if (!(error instanceof RejectedValueError))
+                        throw error;
+                    auditRejectionRefusal(db, error, actor);
+                    return false;
+                }
+                written.push(stamped);
+                return true;
+            });
+        });
+    }, openStore);
+    for (const entry of written)
+        writeEntryMirrors(hippoRoot, entry);
+    return written.length;
 }
-/** Adds `tag` to each of a tenant's rows that lacks it, in `ids` order, each read fresh on one open store and committed alone; an id the tenant does not hold is skipped. */
+/** Adds `tag` to each of a tenant's rows that lacks it, in `ids` order, each read fresh
+ * on one open store and committed alone; an id the tenant does not hold is skipped. */
 export function addTagToEntries(hippoRoot, tenantId, ids, tag) {
-    const db = openStore(hippoRoot);
-    try {
+    onHandle(hippoRoot, (db) => {
         const live = selectEntriesByIds(db, ids, tenantId);
         for (const id of new Set(ids)) {
             const entry = live.get(id);
@@ -64,10 +80,7 @@ export function addTagToEntries(hippoRoot, tenantId, ids, tag) {
                 continue;
             writeEntryOn(db, hippoRoot, { ...entry, tags: [...entry.tags, tag] });
         }
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    }, openStore);
 }
 /** writeEntry on the caller's open store, so a loop of writes opens the store once; each row still commits alone. */
 function writeEntryOn(db, hippoRoot, entry, opts) {
@@ -86,19 +99,8 @@ function writeEntryOn(db, hippoRoot, entry, opts) {
         throw error;
     }
 }
-/**
- * DB-only write path. Caller owns the open `db` handle. Runs upsert +
- * afterWrite hook + audit row inside one withWriteScope. Caller
- * is responsible for opening `db`, optionally wrapping in a larger BEGIN/
- * COMMIT (e.g. supersede's BEGIN IMMEDIATE), closing `db`, AND calling
- * `writeEntryMirrors` after the larger tx commits — mirrors must run
- * post-commit so a rolled-back tx never leaves orphan markdown.
- *
- * Audit-order note: the audit row is emitted INSIDE the write scope, so audit
- * commits atomically with the row INSERT. A subsequent mirror failure cannot
- * leave a recorded audit entry without its corresponding DB row. This is a
- * documented hardening over the prior writeEntry-as-monolith ordering.
- */
+/** DB-only write path: upsert, afterWrite hook and audit row inside one withWriteScope; the caller owns `db` and must call `writeEntryMirrors` after any
+ * outer tx commits, so a rolled-back tx never leaves orphan markdown. The audit row commits atomically with the INSERT. */
 export function writeEntryDbOnly(db, entry, opts) {
     // Inside a caller's transaction (e.g. supersede's BEGIN IMMEDIATE) the scope is a SAVEPOINT,
     // so a throw here rolls back only this write and leaves the outer open.
@@ -147,7 +149,7 @@ export function strengthenRetrieved(hippoRoot, ids, opts) {
         closeHippoDb(db);
     }
 }
-/** strengthenRetrieved on an open handle that holds no transaction, so a recall's last writes share one handle. */
+/** strengthenRetrieved on an open handle in its own write scope, a savepoint inside a caller's transaction, so a recall's last writes share one handle. */
 export function strengthenRetrievedInOwnTx(db, ids, opts) {
     if (ids.length === 0 || opts.recallBoostAblated)
         return new Set();
@@ -170,7 +172,7 @@ export function strengthenRetrievedOn(db, ids, opts) {
     const byId = selectEntriesByIds(db, ids, opts.tenantId);
     const live = [...new Set(ids)].flatMap((id) => byId.get(id) ?? []);
     const update = db.prepare('UPDATE memories SET retrieval_count = ?, last_retrieved = ?, half_life_days = ?, strength = ? WHERE id = ?');
-    for (const e of markRetrieved(live)) {
+    for (const e of markRetrieved(live, undefined, { ablation: strengthAblation() })) {
         update.run(e.retrieval_count, e.last_retrieved, e.half_life_days, e.strength, e.id);
         found.add(e.id);
     }

package/dist/store/failure-log-at.d.ts

@@ -0,0 +1,8 @@
+import { type FailureEvent, type FailureOutcome } from './failure-log.js';
+/** {@link recordFailure} on a handle of its own. */
+export declare function recordFailureAt(hippoRoot: string, event: FailureEvent): number;
+/** {@link requestOutcome} on a handle of its own. */
+export declare function requestOutcomeAt(hippoRoot: string, tenantId: string, requestId: string, sessionId: string): FailureOutcome | null;
+/** {@link settleFailureOutcome} on a handle of its own. */
+export declare function settleFailureOutcomeAt(hippoRoot: string, tenantId: string, requestId: string, outcome: FailureOutcome): void;
+//# sourceMappingURL=failure-log-at.d.ts.map

package/dist/store/failure-log-at.js

@@ -0,0 +1,16 @@
+// The failure log on a handle of its own, for code that has a folder and no connection.
+import { onHandle } from './open.js';
+import { recordFailure, requestOutcome, settleFailureOutcome } from './failure-log.js';
+/** {@link recordFailure} on a handle of its own. */
+export function recordFailureAt(hippoRoot, event) {
+    return onHandle(hippoRoot, (db) => recordFailure(db, event));
+}
+/** {@link requestOutcome} on a handle of its own. */
+export function requestOutcomeAt(hippoRoot, tenantId, requestId, sessionId) {
+    return onHandle(hippoRoot, (db) => requestOutcome(db, tenantId, requestId, sessionId));
+}
+/** {@link settleFailureOutcome} on a handle of its own. */
+export function settleFailureOutcomeAt(hippoRoot, tenantId, requestId, outcome) {
+    onHandle(hippoRoot, (db) => settleFailureOutcome(db, tenantId, requestId, outcome));
+}
+//# sourceMappingURL=failure-log-at.js.map

package/dist/store/failure-log.d.ts

@@ -28,8 +28,8 @@ export interface FailureEvent {
     /** Override the timestamp (tests). ISO string. */
     now?: string;
 }
-/** Append one failure row and prune rows past {@link FAILURE_LOG_RETENTION_DAYS}. */
-export declare function recordFailure(db: DatabaseSyncLike, event: FailureEvent): void;
+/** Prune rows past {@link FAILURE_LOG_RETENTION_DAYS}, then append one failure row; returns the new row's id. */
+export declare function recordFailure(db: DatabaseSyncLike, event: FailureEvent): number;
 /** The outcome logged for a caller's request id, or null, so a retried send finds the first one; another session's id is a ConflictError. */
 export declare function requestOutcome(db: DatabaseSyncLike, tenantId: string, requestId: string, sessionId: string): FailureOutcome | null;
 /** A retry that stored what the first try could not rewrites that row, since the request id allows one row per tenant. */

package/dist/store/failure-log.js

@@ -5,14 +5,16 @@ import { DAY_MS } from '../util/time.js';
 export const FAILURE_LOG_RETENTION_DAYS = 90;
 /** Longest session id or tool name kept; the hook payload is not trusted to be short. */
 const MAX_FIELD = 128;
-/** Append one failure row and prune rows past {@link FAILURE_LOG_RETENTION_DAYS}. */
+/** Prune rows past {@link FAILURE_LOG_RETENTION_DAYS}, then append one failure row; returns the new row's id. */
 export function recordFailure(db, event) {
     // Normalised, because the window and prune compare timestamps as strings.
     const now = new Date(event.now ?? Date.now()).toISOString();
-    db.prepare(`INSERT INTO failure_log (ts, tenant_id, session_id, tool, outcome, skip_rule, sig_hash, detail_hash, owner_subject, origin_project, request_id)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(now, event.tenantId, event.sessionId?.slice(0, MAX_FIELD) ?? null, event.tool?.slice(0, MAX_FIELD) ?? null, event.outcome, event.rule ?? null, event.sigHash ?? null, event.detailHash ?? null, event.ownerSubject ?? null, event.originProject ?? null, event.requestId ?? null);
+    // Prune first: nothing after the insert can throw, so a returned id always means a committed row.
     const cutoff = new Date(Date.parse(now) - FAILURE_LOG_RETENTION_DAYS * DAY_MS).toISOString();
     db.prepare(`DELETE FROM failure_log WHERE ts < ?`).run(cutoff);
+    const inserted = db.prepare(`INSERT INTO failure_log (ts, tenant_id, session_id, tool, outcome, skip_rule, sig_hash, detail_hash, owner_subject, origin_project, request_id)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(now, event.tenantId, event.sessionId?.slice(0, MAX_FIELD) ?? null, event.tool?.slice(0, MAX_FIELD) ?? null, event.outcome, event.rule ?? null, event.sigHash ?? null, event.detailHash ?? null, event.ownerSubject ?? null, event.originProject ?? null, event.requestId ?? null);
+    return Number(inserted.lastInsertRowid);
 }
 /** The outcome logged for a caller's request id, or null, so a retried send finds the first one; another session's id is a ConflictError. */
 export function requestOutcome(db, tenantId, requestId, sessionId) {

package/dist/{trust → store}/gated-write.d.ts

@@ -1,7 +1,9 @@
 import type { DatabaseSyncLike } from '../db/index.js';
 import type { MemoryEntry } from '../core/memory.js';
 export type GatedWriteResult = 'written' | 'skipped:not-worth-storing' | 'skipped:secret' | 'skipped:rejected';
-/** Runs on the caller's handle so it nests in the caller's transaction (writeEntry would open a second handle and wait on that lock); the caller mirrors after commit with an entry it stamped itself. The rejection audit lands inside that transaction, which is safe because a batch that rolls back stays `summarised` and replay writes the audit again. */
+/** Runs on the caller's handle so it nests in the caller's transaction (writeEntry would open a second handle and wait on that lock); the
+ * caller mirrors after commit with an entry it stamped itself. The rejection audit lands inside that transaction, which is safe because
+ * a batch that rolls back stays `summarised` and replay writes the audit again. */
 export declare function gatedWrite(db: DatabaseSyncLike, hippoRoot: string, entry: MemoryEntry, opts?: {
     actor?: string;
     worthCheck?: boolean;

package/dist/{trust → store}/gated-write.js

@@ -1,11 +1,13 @@
 // The one write path for text no person typed into hippo: capture, compaction items and imported agent memories.
 import { isContentWorthStoring } from '../core/memory-quality.js';
-import { RejectedValueError } from '../store/rejection.js';
+import { RejectedValueError } from '../core/api-errors.js';
 import { detectSecret } from '../util/secret-detect.js';
-import { auditRejectionRefusal } from '../store/audit-event.js';
-import { stampOriginProject } from '../store/entry-row.js';
-import { writeEntryDbOnly } from '../store/entry-writes.js';
-/** Runs on the caller's handle so it nests in the caller's transaction (writeEntry would open a second handle and wait on that lock); the caller mirrors after commit with an entry it stamped itself. The rejection audit lands inside that transaction, which is safe because a batch that rolls back stays `summarised` and replay writes the audit again. */
+import { auditRejectionRefusal } from './audit-event.js';
+import { stampOriginProject } from './entry-row.js';
+import { writeEntryDbOnly } from './entry-writes.js';
+/** Runs on the caller's handle so it nests in the caller's transaction (writeEntry would open a second handle and wait on that lock); the
+ * caller mirrors after commit with an entry it stamped itself. The rejection audit lands inside that transaction, which is safe because
+ * a batch that rolls back stays `summarised` and replay writes the audit again. */
 export function gatedWrite(db, hippoRoot, entry, opts) {
     // Off for imported agent memories: a person wrote those notes, and a one-line preference fails the check.
     if (opts?.worthCheck !== false && !isContentWorthStoring(entry.content))

package/dist/store/goals.d.ts

@@ -1,6 +1,4 @@
 import { type DatabaseSyncLike } from '../db/index.js';
-import type { MemoryEntry } from '../core/memory.js';
-import type { RerankStep } from '../core/search-types.js';
 export type GoalStatus = 'active' | 'suspended' | 'completed';
 export type PolicyType = 'schema-fit-biased' | 'error-prioritized' | 'recency-first' | 'hybrid';
 export interface GoalRow {
@@ -81,50 +79,15 @@ export interface GoalRecallLogRow {
     recalledAt: string;
     score: number;
 }
-/** Options of {@link boostByGoals}. */
-export interface GoalStackBoostOpts {
-    sessionId: string;
-    tenantId: string;
-    limit: number;
-    /**
-     * Optional side-channel: one goal-boost `RerankStep` per boosted row, keyed by
-     * `entry.id`. A map rather than a row field because the helper re-spreads rows.
-     * Only populated when passed, so the default path allocates nothing.
-     */
-    trace?: Map<string, RerankStep>;
-}
-/** The boosted, re-sorted rows and the `goal_recall_log` rows they earn. */
-export interface GoalStackBoost<R> {
-    results: R[];
-    log: GoalRecallLogRow[];
-}
 /** The rows whose memory lives in this store: goal_recall_log.memory_id references memories, so a global row would fail
  *  the insert. A global result keeps its boost; it only earns no log row, so no outcome propagation. */
 export declare function localGoalRecallRows(db: DatabaseSyncLike, rows: readonly GoalRecallLogRow[]): GoalRecallLogRow[];
-/** The goal-stack boost over goals already read, touching no store; a caller skips it under an explicit goal tag. Its log covers the top
- *  `limit` rows and keeps those whose memory is global, since only the store can tell them apart; {@link localGoalRecallRows} drops those before the write. */
-export declare function boostByGoals<R extends {
-    entry: MemoryEntry;
-    score: number;
-}>(results: R[], active: ActiveGoals, opts: GoalStackBoostOpts): GoalStackBoost<R>;
-/**
- * Writes goal-boost log rows. INSERT OR IGNORE because UNIQUE(memory_id, goal_id)
- * makes a re-recall during the same goal life a no-op for outcome attribution.
- */
+/** INSERT OR IGNORE: UNIQUE(memory_id, goal_id) makes a re-recall during the same goal life a no-op for outcome attribution. */
 export declare function writeGoalRecallLog(db: DatabaseSyncLike, rows: readonly GoalRecallLogRow[]): void;
 export interface CompleteGoalOpts {
     outcomeScore?: number;
-    /**
-     * When true, skip the strength-multiplier propagation block.
-     * Default false (propagate). The goal's status still transitions to
-     * 'completed' and `outcome_score` is still recorded; only the side-effect
-     * on recalled memories' strength is suppressed.
-     *
-     * Note: the status-check idempotency guard short-circuits a second
-     * `completeGoal` call BEFORE this flag is read, so a noPropagate=true
-     * second call after a propagating first call is a true no-op (propagation
-     * already happened on call 1; call 2 returns early regardless).
-     */
+    /** When true, skip the strength-multiplier propagation (default false); status still goes to 'completed' and `outcome_score` is still recorded.
+     * The idempotency guard returns early on a second `completeGoal` call before this flag is read. */
     noPropagate?: boolean;
 }
 export declare function completeGoal(hippoRoot: string, goalId: string, opts: CompleteGoalOpts): void;