hippo-memory 1.72.0 → 2.0.0

package/dist/store/entry-writes.js

@@ -2,6 +2,7 @@ import { strengthAblation } from '../core/ablation.js';
 import { markRetrieved } from '../core/memory.js';
 import { closeHippoDb, openHippoDb, withWriteScope } from '../db/index.js';
 import { rethrowIfSqliteBlocked } from '../util/sqlite-blocked.js';
+import { chunked } from '../util/chunked.js';
 import { RejectedValueError } from '../core/api-errors.js';
 import { markSummaryDirtyInTx } from './summary-dirty.js';
 import { errorMessage, log } from '../util/log.js';
@@ -10,9 +11,13 @@ import { selectEntriesByIds } from './entry-reads.js';
 import { stampOriginProject, upsertEntryRow, syncFtsRow, deleteFtsRow } from './entry-row.js';
 import { mirrorBestEffort, writeMarkdownMirror } from './mirrors.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. */
+/** Write an entry to SQLite and refresh mirrors. `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) {
+    writeEntryWithHook(hippoRoot, entry, opts);
+}
+/** writeEntry for store code that needs the write's own handle: `opts.afterWrite` shares the INSERT's SAVEPOINT. */
+export function writeEntryWithHook(hippoRoot, entry, opts) {
     onHandle(hippoRoot, (db) => {
         writeEntryOn(db, hippoRoot, entry, opts);
     }, openStore);
@@ -117,11 +122,11 @@ export function auditEntryWrite(db, entry, actor) {
     audit(db, 'remember', { targetId: entry.id, metadata: {
             kind: entry.kind ?? 'distilled',
             scope: entry.scope ?? null,
-        }, actor, tenantId: entry.tenantId });
+        }, actor, tenantId: entry.tenant_id });
     // A child write marks its summary parent dirty for the sleep-cycle rebuild; most writes
     // have no parent, so the hot path pays one null check.
     if (entry.dag_parent_id) {
-        markSummaryDirtyInTx(db, entry.dag_parent_id, entry.tenantId, actor);
+        markSummaryDirtyInTx(db, entry.dag_parent_id, entry.tenant_id, actor);
     }
 }
 /** Markdown mirror path, invoked AFTER commit (a rolled-back tx must leave no orphan markdown). */
@@ -164,6 +169,8 @@ export function strengthenRetrievedInOwnTx(db, ids, opts) {
 function warnStrengthenFailed(error) {
     log.warn(`retrieval stats not saved (${errorMessage(error)})`);
 }
+/** Rows per recall-write statement: five bound values each, far under SQLite's parameter limit. */
+const RETRIEVAL_UPDATE_CHUNK = 100;
 /** strengthenRetrieved on the caller's handle, inside the caller's transaction. Throws; the caller decides. */
 export function strengthenRetrievedOn(db, ids, opts) {
     const found = new Set();
@@ -171,25 +178,30 @@ export function strengthenRetrievedOn(db, ids, opts) {
         return found;
     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, undefined, { ablation: strengthAblation() })) {
-        update.run(e.retrieval_count, e.last_retrieved, e.half_life_days, e.strength, e.id);
-        found.add(e.id);
+    const updated = markRetrieved(live, undefined, { ablation: strengthAblation() });
+    // One UPDATE ... FROM per chunk of rows instead of one statement per row.
+    for (const chunk of chunked(updated, RETRIEVAL_UPDATE_CHUNK)) {
+        const values = chunk.map(() => '(?, ?, ?, ?, ?)').join(', ');
+        db.prepare(`WITH v(id, rc, lr, hl, st) AS (VALUES ${values})
+       UPDATE memories SET retrieval_count = v.rc, last_retrieved = v.lr, half_life_days = v.hl, strength = v.st
+       FROM v WHERE memories.id = v.id`).run(...chunk.flatMap((e) => [e.id, e.retrieval_count, e.last_retrieved, e.half_life_days, e.strength]));
+        for (const e of chunk)
+            found.add(e.id);
     }
     return found;
 }
 /** Rewrites a live row's tags and its full-text row on the caller's transaction, with no audit row. */
 export function setEntryTagsInTx(db, entry) {
     db.prepare(`UPDATE memories SET tags_json = ?, updated_at = datetime('now') WHERE id = ? AND tenant_id = ?`)
-        .run(JSON.stringify(entry.tags), entry.id, entry.tenantId);
+        .run(JSON.stringify(entry.tags), entry.id, entry.tenant_id);
     syncFtsRow(db, entry);
 }
 /** Removes a row from `memories` and full-text search on the caller's transaction, as sleep's dormant move does, and marks its summary parent dirty. */
 export function deleteEntryRowInTx(db, entry, actor) {
-    db.prepare('DELETE FROM memories WHERE id = ? AND tenant_id = ?').run(entry.id, entry.tenantId);
+    db.prepare('DELETE FROM memories WHERE id = ? AND tenant_id = ?').run(entry.id, entry.tenant_id);
     deleteFtsRow(db, entry.id);
     if (entry.dag_parent_id)
-        markSummaryDirtyInTx(db, entry.dag_parent_id, entry.tenantId, actor);
+        markSummaryDirtyInTx(db, entry.dag_parent_id, entry.tenant_id, actor);
 }
 /** One half-life per memory id, on the caller's transaction. */
 export function setHalfLivesAt(db, rows) {

package/dist/store/goals.js

@@ -2,6 +2,7 @@
 import { randomUUID } from 'node:crypto';
 import { withWriteScope } from '../db/index.js';
 import { onHandle } from './open.js';
+import { placeholders } from '../util/sql.js';
 const MAX_ACTIVE_GOAL_DEPTH = 3;
 export function rowToGoal(row) {
     return {
@@ -152,7 +153,7 @@ function loadGoalPolicies(db, active) {
     // SAFETY: the SELECT projects exactly these seven retrieval_policy columns; MAX_ACTIVE_GOAL_DEPTH bounds the IN list.
     const rows = db.prepare(`
     SELECT id, goal_id, policy_type, weight_schema_fit, weight_recency, weight_outcome, error_priority
-    FROM retrieval_policy WHERE id IN (${policyIds.map(() => '?').join(',')})
+    FROM retrieval_policy WHERE id IN (${placeholders(policyIds.length)})
   `).all(...policyIds);
     const byId = new Map(rows.map((row) => [row.id, row]));
     for (const g of active) {
@@ -178,7 +179,7 @@ export function localGoalRecallRows(db, rows) {
         return [];
     const ids = [...new Set(rows.map((r) => r.memoryId))];
     // SAFETY: the SELECT projects exactly one column, `id`, from memories.
-    const local = db.prepare(`SELECT id FROM memories WHERE id IN (${ids.map(() => '?').join(',')})`).all(...ids);
+    const local = db.prepare(`SELECT id FROM memories WHERE id IN (${placeholders(ids.length)})`).all(...ids);
     const localIds = new Set(local.map((r) => r.id));
     return rows.filter((r) => localIds.has(r.memoryId));
 }

package/dist/store/graph-reads.js

@@ -4,6 +4,7 @@ import { openHippoDb, closeHippoDb, withReadSnapshot } from '../db/index.js';
 import { onHandle } from './open.js';
 import { assertTenantId } from './tenant.js';
 import { GRAPH_ENTITY_TYPES, rowToEntity, rowToRelation, ENTITY_COLS, RELATION_COLS } from './graph-rows.js';
+import { placeholders } from '../util/sql.js';
 const DEFAULT_GRAPH_PAGE_SIZE = DEFAULT_LIST_LIMIT;
 const DEFAULT_GRAPH_SCAN_LIMIT = 1000;
 /** Entities with an exact `name`, bounded by `limit` in SQL with a deterministic order, so graph-view focus finds `--entity NAME` directly
@@ -100,7 +101,7 @@ export function loadEntitiesByIds(hippoRoot, tenantId, ids, txDb) {
         const out = [];
         for (let i = 0; i < ids.length; i += IN_LIST_CHUNK) {
             const slice = ids.slice(i, i + IN_LIST_CHUNK);
-            const ph = slice.map(() => '?').join(',');
+            const ph = placeholders(slice.length);
             // SAFETY: rows' shape matches the columns named in ENTITY_COLS above.
             const rows = db.prepare(`
         SELECT ${ENTITY_COLS} FROM entities
@@ -133,7 +134,7 @@ export function loadNeighborRelations(hippoRoot, tenantId, entityIds, opts = {},
         const byId = new Map();
         for (let i = 0; i < entityIds.length; i += IN_LIST_CHUNK) {
             const slice = entityIds.slice(i, i + IN_LIST_CHUNK);
-            const ph = slice.map(() => '?').join(',');
+            const ph = placeholders(slice.length);
             // SAFETY: rows' shape matches the columns named in RELATION_COLS above.
             const rows = db.prepare(`
         SELECT ${RELATION_COLS} FROM relations
@@ -164,7 +165,7 @@ export function loadRelationsAmong(hippoRoot, tenantId, entityIds, opts = {}, tx
     const ownDb = txDb ? null : openHippoDb(hippoRoot);
     const db = txDb ?? ownDb;
     try {
-        const ph = entityIds.map(() => '?').join(',');
+        const ph = placeholders(entityIds.length);
         // SAFETY: rows' shape matches the columns named in RELATION_COLS above.
         const rows = db.prepare(`
       SELECT ${RELATION_COLS} FROM relations
@@ -189,7 +190,7 @@ export function loadEntitiesByMemoryId(hippoRoot, tenantId, memoryIds) {
         const out = [];
         for (let i = 0; i < memoryIds.length; i += IN_LIST_CHUNK) {
             const slice = memoryIds.slice(i, i + IN_LIST_CHUNK);
-            const ph = slice.map(() => '?').join(',');
+            const ph = placeholders(slice.length);
             // id ASC so chunk-local scan order never decides ties (id is an autoincrement PK).
             // SAFETY: rows' shape matches the columns named in ENTITY_COLS above.
             const rows = db.prepare(`

package/dist/store/graph-view-rows.js

@@ -1,4 +1,5 @@
 import { IN_LIST_CHUNK, loadEntities, loadEntitiesByIds, loadEntitiesByName, loadNeighborRelations, loadRelations, loadRelationsAmong } from './graph-reads.js';
+import { placeholders } from '../util/sql.js';
 /** The items whose source memory `canRead` admits: a NULL memoryId has no scope to hide, and a missing memory fails closed. */
 function readableOnly(db, tenantId, items, canRead) {
     if (!canRead)
@@ -8,7 +9,7 @@ function readableOnly(db, tenantId, items, canRead) {
     for (let i = 0; i < ids.length; i += IN_LIST_CHUNK) {
         const slice = ids.slice(i, i + IN_LIST_CHUNK);
         // SAFETY: rows' shape matches the id and scope columns named in the SELECT.
-        const rows = db.prepare(`SELECT id, scope FROM memories WHERE +tenant_id = ? AND id IN (${slice.map(() => '?').join(',')})`)
+        const rows = db.prepare(`SELECT id, scope FROM memories WHERE +tenant_id = ? AND id IN (${placeholders(slice.length)})`)
             .all(tenantId, ...slice);
         for (const r of rows)
             if (canRead(r.scope))

package/dist/store/half-life.js

@@ -34,9 +34,9 @@ function writeMove(db, move, old, actor) {
     const byTenant = new Map();
     for (const e of move.entries) {
         // One record per tenant, filled in place: copying it per row made the write grow with the square of the store.
-        let record = byTenant.get(e.tenantId);
+        let record = byTenant.get(e.tenant_id);
         if (!record)
-            byTenant.set(e.tenantId, (record = {}));
+            byTenant.set(e.tenant_id, (record = {}));
         record[e.id] = old.get(e.id);
     }
     for (const [tenantId, oldHalfLives] of byTenant) {

package/dist/store/handoffs.d.ts

@@ -17,10 +17,16 @@ export declare function loadLatestHandoff(hippoRoot: string, tenantId: string, s
 export declare function loadHandoffById(hippoRoot: string, tenantId: string, id: number): SessionHandoff | null;
 /** Stamp the outcome on a session's newest handoff, only if it has none yet. Returns rows changed. */
 export declare function stampHandoffOutcome(hippoRoot: string, tenantId: string, sessionId: string, outcome: HandoffOutcome): number;
+export interface SessionEndHandoffRequest {
+    readonly tenantId: string;
+    readonly sessionId: string;
+    readonly evidence: HandoffEvidence | null;
+    readonly derived?: Pick<TaskSnapshot, 'task' | 'summary' | 'next_step'> | null;
+    readonly key?: ContinuityKey;
+    readonly inPlace?: boolean;
+}
 /** Session-end handoff from the active snapshot, else `derived` transcript state; `inPlace` rewrites an earlier transcript read instead of adding a revision.
  * Returns null when no source is the session's, a newer handoff covers it, or the latest one is not transcript-derived or already holds `derived`. */
-export declare function writeSessionEndHandoff(hippoRoot: string, tenantId: string, sessionId: string, evidence: HandoffEvidence | null, derived?: Pick<TaskSnapshot, 'task' | 'summary' | 'next_step'> | null, key?: ContinuityKey, options?: {
-    inPlace?: boolean;
-}): SessionHandoff | null;
+export declare function writeSessionEndHandoff(hippoRoot: string, request: SessionEndHandoffRequest): SessionHandoff | null;
 export {};
 //# sourceMappingURL=handoffs.d.ts.map

package/dist/store/handoffs.js

@@ -169,7 +169,8 @@ function buildSessionEndHandoff(sessionId, snapshot, existing, handoffEvidence,
 }
 /** Session-end handoff from the active snapshot, else `derived` transcript state; `inPlace` rewrites an earlier transcript read instead of adding a revision.
  * Returns null when no source is the session's, a newer handoff covers it, or the latest one is not transcript-derived or already holds `derived`. */
-export function writeSessionEndHandoff(hippoRoot, tenantId, sessionId, evidence, derived = null, key, options = {}) {
+export function writeSessionEndHandoff(hippoRoot, request) {
+    const { tenantId, sessionId, evidence, derived = null, key, inPlace } = request;
     assertTenantId('writeSessionEndHandoff', tenantId);
     if (key)
         continuityStamp(key); // a partial key is a caller bug, so fail loud rather than write nothing
@@ -179,7 +180,7 @@ export function writeSessionEndHandoff(hippoRoot, tenantId, sessionId, evidence,
     let handoffEvidence = evidence;
     let fromTranscript = false;
     // After every reply the transcript is newer than the last compaction's snapshot, which the open chat keeps for the next one.
-    const snapshotGivesWay = options.inPlace === true && derived !== null && active?.source === 'pre-compact';
+    const snapshotGivesWay = inPlace === true && derived !== null && active?.source === 'pre-compact';
     if (active && active.session_id === sessionId && !snapshotGivesWay) {
         // Strict '>': a same-millisecond tie must not swallow the session's only write (test 6e).
         if (existing && existing.updatedAt > active.updated_at)
@@ -197,7 +198,7 @@ export function writeSessionEndHandoff(hippoRoot, tenantId, sessionId, evidence,
     const outcome = sessionOutcome(hippoRoot, tenantId, sessionId);
     const handoff = buildSessionEndHandoff(sessionId, snapshot, existing, handoffEvidence, outcome);
     // A miss means a handoff landed since the read, and a new transcript row would hide it.
-    if (fromTranscript && options.inPlace && existing)
+    if (fromTranscript && inPlace && existing)
         return replaceTranscriptHandoff(hippoRoot, tenantId, handoff, key);
     return saveSessionHandoff(hippoRoot, tenantId, handoff, key);
 }

package/dist/store/index.d.ts

@@ -1,4 +1,4 @@
-export type { AmbientCandidateRequest, ContextReads, EntryRemoval, EntryTarget, EntryWrite, EntryWrites, HippoStore, KeyAudit, KeyListQuery, KeyMint, KeyRevoke, KeyWrites, OutcomeWrite, RawArchive, RecallSearchArgs, RecallWrites, SelfKeyMint, StoreGroup, StoreGroups, SupersedeWrite, VectorBackfillQuery, VectorReads, VectorRowWrite, VectorWrite, VectorWriteResult, VectorWrites, } from './port.js';
+export type { AmbientCandidateRequest, ContextReads, EntryRemoval, EntryTarget, EntryWrite, EntryWrites, HippoStore, KeyAudit, KeyListQuery, KeyMint, KeyRevoke, KeyWrites, LastRecall, LastRecallWrites, OutcomeWrite, RawArchive, RecallSearchArgs, RecallWrites, SelfKeyMint, StoreGroup, StoreGroups, SupersedeWrite, VectorBackfillQuery, VectorReads, VectorRowWrite, VectorWrite, VectorWriteResult, VectorWrites, } from './port.js';
 export { hasGroup, requireGroup } from './port.js';
-export * from './sqlite/store.js';
+export { sqliteStore } from './sqlite/store.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/store/index.js

@@ -1,3 +1,3 @@
 export { hasGroup, requireGroup } from './port.js';
-export * from './sqlite/store.js';
+export { sqliteStore } from './sqlite/store.js';
 //# sourceMappingURL=index.js.map

package/dist/store/mirrors.js

@@ -8,7 +8,12 @@ import { oncePerStore } from '../db/connect.js';
 import { errorFields, errorMessage, log } from '../util/log.js';
 import { parseJsonArray, INDEX_VERSION, parseLastTraceId, MEMORY_SELECT_COLUMNS, rowToEntry, rowToMemoryConflict, } from './rows.js';
 import { serializeEntry } from '../core/markdown.js';
+import { writeFileAtomic } from '../util/atomic-write.js';
 const SCORE_DECIMALS = 3;
+// Mirrors are derived and rebuildable from the store, so they skip the fsyncs (the cost on Windows) and keep the temp-and-rename atomicity.
+function writeMirror(file, text) {
+    writeFileAtomic(file, text, { durable: false });
+}
 export function layerDir(root, layer) {
     return path.join(root, layer);
 }
@@ -61,7 +66,7 @@ export function writeActiveTaskMirror(hippoRoot, tenantId, snapshot) {
         body.push(`## Session`, snapshot.session_id, '');
     }
     fs.mkdirSync(path.dirname(filePath), MIRROR_FOLDER);
-    fs.writeFileSync(filePath, `${fm}\n\n${body.join('\n')}`, 'utf8');
+    writeMirror(filePath, `${fm}\n\n${body.join('\n')}`);
 }
 export function removeActiveTaskMirror(hippoRoot, tenantId) {
     const filePath = activeTaskMirrorPath(hippoRoot, tenantId);
@@ -99,7 +104,7 @@ export function writeRecentSessionMirror(hippoRoot, tenantId, events) {
     }
     lines.push('');
     fs.mkdirSync(path.dirname(filePath), MIRROR_FOLDER);
-    fs.writeFileSync(filePath, `${fm}\n\n${lines.join('\n')}`, 'utf8');
+    writeMirror(filePath, `${fm}\n\n${lines.join('\n')}`);
 }
 function writeConflictMirrors(hippoRoot, conflicts) {
     const conflictDir = path.join(hippoRoot, 'conflicts');
@@ -128,7 +133,7 @@ function writeConflictMirrors(hippoRoot, conflicts) {
             `- Status: ${conflict.status}`,
             '',
         ].join('\n');
-        fs.writeFileSync(path.join(conflictDir, filename), `${fm}\n\n${body}`, 'utf8');
+        writeMirror(path.join(conflictDir, filename), `${fm}\n\n${body}`);
     }
     for (const existing of fs.readdirSync(conflictDir)) {
         if (existing === '.gitkeep')
@@ -142,7 +147,7 @@ export function writeMarkdownMirror(hippoRoot, entry) {
     removeEntryMirrors(hippoRoot, entry.id);
     const dir = layerDir(hippoRoot, entry.layer);
     fs.mkdirSync(dir, MIRROR_FOLDER);
-    fs.writeFileSync(path.join(dir, `${entry.id}.md`), serializeEntry(entry), 'utf8');
+    writeMirror(path.join(dir, `${entry.id}.md`), serializeEntry(entry));
 }
 // Every layer, Trace included: `writeMarkdownMirror` writes any layer, and a stale trace mirror
 // is the resurrection channel bootstrapLegacyStore/rebuildIndex guard against.

package/dist/store/open.d.ts

@@ -5,7 +5,8 @@ export declare function initStore(hippoRoot: string): void;
 export declare function openStore(hippoRoot: string, opts?: {
     busyWaitMs?: number;
 }): DatabaseSyncLike;
-/** One call on a handle of its own, closed after; pass openStore where the call also sets up mirror folders and legacy rows. */
+/** One call on a handle of its own, closed after (a request scope's handle stays open);
+ *  pass openStore where the call also sets up mirror folders and legacy rows. */
 export declare function onHandle<T>(hippoRoot: string, fn: (db: DatabaseSyncLike) => T, open?: (hippoRoot: string) => DatabaseSyncLike): T;
 /** `meta` key holding the default half-life base a store's memories are on (src/consolidate/half-life-migration.ts). */
 export declare const HALF_LIFE_BASE_META_KEY = "default_half_life_base";

package/dist/store/open.js

@@ -44,7 +44,8 @@ export function openStore(hippoRoot, opts) {
         throw error;
     }
 }
-/** One call on a handle of its own, closed after; pass openStore where the call also sets up mirror folders and legacy rows. */
+/** One call on a handle of its own, closed after (a request scope's handle stays open);
+ *  pass openStore where the call also sets up mirror folders and legacy rows. */
 export function onHandle(hippoRoot, fn, open = openHippoDb) {
     const db = open(hippoRoot);
     try {

package/dist/store/port.d.ts

@@ -1,7 +1,8 @@
 import type { AmbientTallies } from '../core/ambient.js';
 import type { AmbientStoreFilter } from './ambient.js';
 import type { ApiKeyListRow, ApiKeyRecord, ListApiKeysOpts, NewApiKey } from './auth.js';
-import type { AppendAuditOpts, AuditEvent, ListAuditAfterOpts, QueryAuditOpts } from './audit.js';
+import type { AppendAuditOpts, AuditEvent, AuditPrune, ListAuditAfterOpts, QueryAuditOpts } from './audit.js';
+import type { QualityRepairResult } from './quality-repair.js';
 import type { EmbeddingIndexState } from './vector-index.js';
 import type { Entity, Relation } from './graph-rows.js';
 import type { ActiveGoals, GetActiveGoalsOpts, GoalRecallLogRow } from './goals.js';
@@ -17,7 +18,7 @@ import type { ClosureState } from '../core/prediction.js';
 import type { QuarantineRow, QuarantineStatus } from './quarantine.js';
 import type { ScopeActor } from '../core/recall-scope.js';
 import type { RecallTraceInput } from './recall-trace.js';
-import type { AmbientLoadResult, AmbientRecallRequest, ContextCandidateFilter, RecentOrigins } from './candidates.js';
+import type { AmbientLoadResult, AmbientRecallRequest, ContextCandidateFilter, HeldText, RecentOrigins } from './candidates.js';
 import type { GitHubDlqInsert, GitHubRouting } from './connectors/github.js';
 import type { SlackDlqInsert, SlackTeamRoute } from './connectors/slack.js';
 import type { StrengthenOptions } from './entry-writes.js';
@@ -411,6 +412,18 @@ export interface Readiness {
     /** Resolves once one cheap read has answered; rejects with the store's own error when it cannot. */
     ping(): Promise<void>;
 }
+/** A recall's writes when the store keeps it as its last one: `strengthen.ids` are the ids it returned. */
+export type LastRecallWrites = RecallWrites & Required<Pick<RecallWrites, 'strengthen'>>;
+/** The last recall a store keeps, so a later outcome can name it, and the outcome linked to a recall trace. */
+export interface LastRecall {
+    /** entryWrites.applyOutcome, then a link from recall trace `traceId` to the ids applied; resolves to those ids. */
+    applyTracedOutcome(outcome: OutcomeWrite, traceId: number): Promise<string[]>;
+    /** applyTracedOutcome on the ids and trace of the last recall, read together so an outcome never pairs them with an older trace. */
+    applyOutcomeToLast(target: EntryTarget, good: boolean): Promise<string[]>;
+    /** finishRecall, then the ids this store lacks strengthened under `globalRoot`, then the ids and their trace saved as the last
+     *  recall in one write; resolves to the trace id, null when none was asked or its write failed. */
+    finishRecall(writes: LastRecallWrites, globalRoot: string | undefined): Promise<number | null>;
+}
 /** Which of a tenant's quarantine records a list reads; `limit` is 100 when unset. */
 export interface QuarantineListQuery {
     readonly status: QuarantineStatus | 'all';
@@ -575,8 +588,49 @@ export interface VectorViews {
     /** The same ids and values as `VectorReads.storedVectors`, each value a Float32 view. */
     storedVectorViews(ids: readonly string[]): Promise<Map<string, Float32Array>>;
 }
+/** The store is hippo.db and its files under `hippoRoot`, so a path that reopens them by folder (sleep, its child process, the global store) may run. */
+export interface LocalFiles {
+    readonly hippoRoot: string;
+}
+/** The reads and writes behind the memory-quality audit, its repair and audit-log retention. */
+export interface AuditMaintenance {
+    /** Every memory of the tenant, in `loadAllEntries` order. */
+    tenantEntries(tenantId: string): Promise<MemoryEntry[]>;
+    /** The ids of every memory a typed object row names, in any tenant; an automatic pass never deletes one. */
+    objectBackedIds(): Promise<Set<string>>;
+    /** Deletes each removal's row with its own forget row, leaving a pinned, raw, kept or object-backing row; resolves to the ids deleted. */
+    deleteAutomatically(removals: readonly {
+        readonly id: string;
+        readonly reason: string;
+    }[], actor: string): Promise<string[]>;
+    /** Counts (dryRun) or deletes the tenant's audit rows before `cutoff`, then appends one audit_prune row; resolves to the count. */
+    pruneAuditRows(prune: AuditPrune): Promise<number>;
+    /** A preview, or with `apply` the moves of certain defects to dormant storage behind a backup. */
+    repairQuality(tenantId: string, apply: boolean): Promise<QualityRepairResult>;
+    /** repairQuality applied once per store; null once it ran there. */
+    repairQualityOnce(tenantId: string): Promise<QualityRepairResult | null>;
+}
+/** The reads and writes behind git auto-learn's batch. */
+export interface LessonWrites {
+    /** Every memory of the tenant, in `loadAllEntries` order. */
+    tenantEntries(tenantId: string): Promise<MemoryEntry[]>;
+    /** Content, source and origin of the tenant's rows holding any of `words`, among the rows a team member or `ownScope`'s owner may touch. */
+    textsHoldingWords(tenantId: string, words: readonly string[], ownScope: string | null): Promise<HeldText[]>;
+    /** Writes each entry in one transaction; a rejected value writes its refusal row and is skipped. Resolves to the ids written. */
+    writeSkippingRejected(entries: readonly MemoryEntry[], actor: string): Promise<string[]>;
+    /** Rewrites each entry in one transaction, all or none. */
+    writeTogether(entries: readonly MemoryEntry[]): Promise<void>;
+    /** Adds `count` to the store-wide remembered counter. */
+    bumpRemembered(count: number): Promise<void>;
+}
 /** The optional groups: a store sets each one whole or leaves it unset, and a route or MCP tool names the one it needs. */
 export interface StoreGroups {
+    /** Unset on any store but hippo.db; a request then runs fenced from hippo.db, and a route or tool that names no group answers 501. */
+    readonly localFiles: LocalFiles;
+    /** Unset on a store without it, where the quality audit, its repair and audit prune answer 501. */
+    readonly auditMaintenance: AuditMaintenance;
+    /** Unset on a store without it, where git learn answers 501. */
+    readonly lessonWrites: LessonWrites;
     /** Unset on a store built before them, where hybrid and physics recall under an embedding provider answer 501. */
     readonly vectors: VectorReads;
     /** Unset on a store without them, where recall scores the number[] copies `vectors` returns, to the same ranking. */
@@ -599,6 +653,8 @@ export interface StoreGroups {
     readonly objects: Objects;
     /** Unset on a store built before it, where GET /ready answers 200 with `store: "unchecked"`. */
     readonly readiness: Readiness;
+    /** Unset on a store that keeps no last recall, where outcomeForLastRecall and a traced outcome answer 501 and context writes no last recall. */
+    readonly lastRecall: LastRecall;
 }
 export type StoreGroup = 'base' | keyof StoreGroups;
 export declare function hasGroup(store: HippoStore, group: StoreGroup): boolean;
@@ -612,7 +668,7 @@ export declare class StoreBusyError extends Error {
 /** What `serve()` reads and writes through. Each method is atomic and no transaction spans an
  * await, since SQLite's lock wait blocks the event loop; a lock timeout throws `StoreBusyError`. */
 export interface HippoStore extends Partial<StoreGroups> {
-    /** 'sqlite' is hippo.db under the served root. Under any other kind, an unported route answers 501 and a hippo.db open inside a request throws. */
+    /** A name for logs and errors; what a store can do is the groups it sets, `localFiles` above all. */
     readonly kind: string;
     /** The api_keys row for `keyId` with its scope grants, revoked or not; null when no row matches. */
     findApiKey(keyId: string): Promise<ApiKeyRecord | null>;

package/dist/store/quality-repair.js

@@ -133,7 +133,7 @@ function setAsideIssue(db, entry, reason, now, backup) {
     if (getMeta(db, 'fts5_available', '0') === '1' && ftsRowExists(db, entry.id)) {
         throw new Error(`Quality repair could not remove the full-text row for ${entry.id}`);
     }
-    appendAuditEvent(db, { tenantId: entry.tenantId, actor, op: 'quality_repair', targetId: entry.id, metadata: { reason, backup } });
+    appendAuditEvent(db, { tenantId: entry.tenant_id, actor, op: 'quality_repair', targetId: entry.id, metadata: { reason, backup } });
     return true;
 }
 function applyPlan(db, root, tenantId, backup, doneKey) {

package/dist/store/recall-trace.js

@@ -7,6 +7,7 @@ import { DELIVERY_LEDGER_VERSION, isBoundaryEvent } from './delivery-recorder.js
 import { errorFields, errorMessage, log } from '../util/log.js';
 import { DAY_MS } from '../util/time.js';
 import { blockHash } from '../util/token-text.js';
+import { placeholders } from '../util/sql.js';
 /** Strip a RerankStep to {stage, multiplier, scoreBefore, scoreAfter}: `note` is free-form (the CLI goal-boost step embeds goal tag text) and would leak
  * user content into `rerank_json`; an allowlist, so any future free-form field is dropped too. */
 function sanitizeRerankSteps(steps) {
@@ -184,7 +185,7 @@ export function writeDeliveryEvent(db, input) {
             ];
             const eventId = Number(db.prepare(`
         INSERT INTO delivery_events (${DELIVERY_EVENT_COLUMNS.join(', ')})
-        VALUES (${DELIVERY_EVENT_COLUMNS.map(() => '?').join(', ')})
+        VALUES (${placeholders(DELIVERY_EVENT_COLUMNS.length)})
       `).run(...values).lastInsertRowid);
             const insertCandidate = db.prepare(`
         INSERT INTO delivery_candidates (event_id, tenant_id, memory_id, source_store, pool, stage, outcome, reason, cand_rank, score, tokens)

package/dist/store/rejected-values.js

@@ -5,7 +5,7 @@ import { heldTexts } from '../util/same-text.js';
 import { audit } from './audit-event.js';
 import { deleteEntryCore } from './delete-and-batch.js';
 import { deleteDormantRow, listDormantSnapshots, purgeDormantByDigest, replaceDormantEntry } from './dormant.js';
-import { entryRejectRowAt, selectAllEntries } from './entry-reads.js';
+import { entryRejectRowAt, selectEntriesByIds, selectTenantTexts } from './entry-reads.js';
 import { stampOriginProject } from './entry-row.js';
 import { writeEntryDbOnly, writeEntryMirrors } from './entry-writes.js';
 import { purgeMirrorBestEffort } from './mirrors.js';
@@ -16,15 +16,20 @@ import { RejectedValueError } from '../core/api-errors.js';
 function removeLiveRows(db, hippoRoot, rejection, holdsValue, removal) {
     const { tenantId, actor, reason } = rejection;
     const { removedIds, removedRawIds, successors } = removal;
-    const merged = [];
-    for (const row of selectAllEntries(db, tenantId)) {
+    // Text columns decide which rows hold the value; only those rows are read whole.
+    const directIds = [];
+    const mergedIds = [];
+    for (const row of selectTenantTexts(db, tenantId)) {
         if (!rejection.inReach(row.scope))
             continue;
-        if (!holdsValue(row.content)) {
-            if (heldTexts(row).some(holdsValue))
-                merged.push(row);
-            continue;
-        }
+        if (holdsValue(row.content))
+            directIds.push(row.id);
+        else if (heldTexts(row).some(holdsValue))
+            mergedIds.push(row.id);
+    }
+    const held = selectEntriesByIds(db, [...directIds, ...mergedIds], tenantId);
+    const merged = mergedIds.flatMap((id) => held.get(id) ?? []);
+    for (const row of directIds.flatMap((id) => held.get(id) ?? [])) {
         if (row.kind === 'raw') {
             // A raw row is append-only: archiving is its one removal path, and its savepoint nests in this write scope.
             archiveRawMemory(db, row.id, { reason, who: actor });
@@ -97,7 +102,7 @@ export function applyRejection(hippoRoot, rejection) {
                 sourceMemoryId: memoryId ?? null,
                 normalizedChars: normalizeValueForRejection(content).length,
             });
-            // SHORTCUT: scans every row of the tenant, fine for a human-run command; a digest column on memories if stores grow a hundredfold.
+            // SHORTCUT: scans the tenant's text columns, fine for a human-run command; a digest column needs a schema migration, held until approved.
             const holdsValue = (text) => rejectionDigest(text) === digest;
             removeLiveRows(db, hippoRoot, rejection, holdsValue, removal);
             removeDormantCopies(db, rejection, digest, holdsValue, removal);

package/dist/store/rows.js

@@ -61,12 +61,12 @@ function rowToPlacementFields(row) {
         scope: row.scope ?? null,
         owner: row.owner ?? null,
         artifact_ref: row.artifact_ref ?? null,
-        tenantId: row.tenant_id ?? DEFAULT_TENANT_ID,
+        tenant_id: row.tenant_id ?? DEFAULT_TENANT_ID,
         origin_project: row.origin_project ?? null,
         descendant_count: Number(row.descendant_count ?? 0),
         earliest_at: row.earliest_at ?? null,
         latest_at: row.latest_at ?? null,
-        summary_dirty: (Number(row.summary_dirty ?? 0) === 1 ? 1 : 0),
+        summary_dirty: Number(row.summary_dirty) === 1,
         last_rebuilt_at: row.last_rebuilt_at ?? null,
         rebuild_count: Number(row.rebuild_count ?? 0),
         dag_level_3_built_at: row.dag_level_3_built_at ?? null,

package/dist/store/rule-sql.d.ts

@@ -1,3 +1,5 @@
+/** calculateRewardFactor as SQL over `memories` columns; strengthSql and the context-candidate rank both build on it, so the slope has one source. */
+export declare function rewardFactorSql(): string;
 /** calculateStrength's clock-basis formula as SQL over `memories` columns, flags and multipliers baked in; keep in step.
  *  An unparseable date scores NULL here and 0 in JS, so sums agree. */
 export declare function strengthSql(now: Date): string;

package/dist/store/rule-sql.js

@@ -3,7 +3,16 @@ import { DAY_MS } from '../util/time.js';
 import { isDecayAblated, isOutcomeSlowAblated, isRecallBoostAblated } from '../core/ablation.js';
 import { DECAY_BASE, EMOTIONAL_MULTIPLIERS, FALLBACK_HALF_LIFE_DAYS, KEEP_PAIRS, MAX_WRONG_HALVINGS, RETRIEVAL_BOOST_SLOPE, REWARD_SLOPE, applyLossAversionRatio, } from '../core/memory.js';
 import { PERSONAL_SCOPE_PREFIX, RECALL_DEFAULT_DENY_SCOPES } from '../core/recall-scope.js';
+import { placeholders } from '../util/sql.js';
 const UNIX_EPOCH_JULIAN_DAY = 2440587.5;
+/** calculateRewardFactor as SQL over `memories` columns; strengthSql and the context-candidate rank both build on it, so the slope has one source. */
+export function rewardFactorSql() {
+    if (isOutcomeSlowAblated())
+        return '1.0';
+    const pos = 'COALESCE(outcome_positive, 0)';
+    const neg = 'COALESCE(outcome_negative, 0)';
+    return `(CASE WHEN ${pos} = 0 AND ${neg} = 0 THEN 1.0 ELSE 1.0 + ${REWARD_SLOPE} * (${pos} - ${neg}) / (${pos} + ${neg} + 1.0) END)`;
+}
 /** calculateStrength's clock-basis formula as SQL over `memories` columns, flags and multipliers baked in; keep in step.
  *  An unparseable date scores NULL here and 0 in JS, so sums agree. */
 export function strengthSql(now) {
@@ -11,10 +20,7 @@ export function strengthSql(now) {
     const pos = 'COALESCE(outcome_positive, 0)';
     const neg = 'COALESCE(outcome_negative, 0)';
     const wrong = isOutcomeSlowAblated() || isDecayAblated() ? '0' : `MAX(0, ${neg} - ${pos})`;
-    const reward = isOutcomeSlowAblated()
-        ? '1.0'
-        : `(CASE WHEN ${pos} = 0 AND ${neg} = 0 THEN 1.0 ELSE 1.0 + ${REWARD_SLOPE} * (${pos} - ${neg}) / (${pos} + ${neg} + 1.0) END)`;
-    const halfLife = `(COALESCE(half_life_days, ${FALLBACK_HALF_LIFE_DAYS}) * ${reward})`;
+    const halfLife = `(COALESCE(half_life_days, ${FALLBACK_HALF_LIFE_DAYS}) * ${rewardFactorSql()})`;
     const anchor = isRecallBoostAblated() ? 'created' : 'last_retrieved';
     const nowJulian = num(now.getTime() / DAY_MS + UNIX_EPOCH_JULIAN_DAY);
     const decay = isDecayAblated() ? '1.0' : `pow(${DECAY_BASE}, (${nowJulian} - julianday(${anchor})) / ${halfLife})`;
@@ -38,8 +44,8 @@ const keepPairSql = (p) => `(COALESCE(superseded_by, '') = '' AND EXISTS (SELECT
 export const AUTO_DELETABLE_SQL = `pinned = 0 AND kind != 'raw'${KEEP_PAIRS.map((p) => ` AND NOT ${keepPairSql(p)}`).join('')}`;
 /** SQL twin of the no-request arm of passesScopeFilterForRecall; `ownScope` is bound and compared with `=`, so `%` or `_` in an owner match nothing extra. */
 export function scopeAdmitSql(col, ownScope) {
-    const placeholders = RECALL_DEFAULT_DENY_SCOPES.map(() => '?').join(', ');
-    const admitted = `${col}scope IS NULL OR (${col}scope NOT IN (${placeholders}) AND ${col}scope NOT LIKE '%:private:%')`;
+    const marks = placeholders(RECALL_DEFAULT_DENY_SCOPES.length);
+    const admitted = `${col}scope IS NULL OR (${col}scope NOT IN (${marks}) AND ${col}scope NOT LIKE '%:private:%')`;
     if (ownScope == null)
         return { sql: `(${admitted})`, params: [...RECALL_DEFAULT_DENY_SCOPES] };
     // The own arm sits inside the outer parentheses so a caller's `AND ${sql}` cannot split it off.

package/dist/store/search-rows.d.ts

@@ -18,13 +18,8 @@ export type OriginFilter = string | readonly string[];
 /** Scope rule for recall: none requested is default-deny; 'exact' narrows to the request; 'additive' adds it to the default set, unless it is personal,
  * which only `ownScope` opens. */
 export declare function recallScopeFilter(requestedScope: string | undefined, mode: 'exact' | 'additive', ownScope?: string): RecallScopeFilter;
-/** Sends term queries down the LIKE path on a build that has FTS. Only tests call it. */
-export declare function _forceLikePathForTests(on: boolean): void;
 /** Load likely search candidates: FTS5 when available, else LIKE, then full-store fallback. With `tenantId` every SELECT filters by it; omitted = no filter. */
 export declare function loadSearchEntries(hippoRoot: string, query: string, limit?: number, tenantId?: string): MemoryEntry[];
-/** Recall-mode loader: scope predicate in SQL so `unknown:legacy` cannot leak. Empty `requestedScope` default-denies (admits `ownScope`); else exact match.
- * SQL `NOT LIKE '%:private:%'` runs before the LIMIT so private rows cannot starve admitted ones; `passesScopeFilterForRecall` is the exact post-filter. */
-export declare function loadRecallSearchEntries(hippoRoot: string, query: string, limit?: number, tenantId?: string, requestedScope?: string, explicitScopeMode?: 'exact' | 'additive', includeSuperseded?: boolean, originProjects?: OriginFilter, ownScope?: string): MemoryEntry[];
 export interface RecallSearchEntriesOptions {
     readonly limit?: number;
     readonly tenantId?: string;
@@ -34,6 +29,11 @@ export interface RecallSearchEntriesOptions {
     readonly originProjects?: OriginFilter;
     readonly ownScope?: string;
 }
+/** Recall-mode loader: scope predicate in SQL so `unknown:legacy` cannot leak. Empty `requestedScope` default-denies (admits `ownScope`); else exact match.
+ * SQL `NOT LIKE '%:private:%'` runs before the LIMIT so private rows cannot starve admitted ones; `passesScopeFilterForRecall` is the exact post-filter. */
+export declare function loadRecallEntries(hippoRoot: string, query: string, options?: RecallSearchEntriesOptions): MemoryEntry[];
+/** Positional form of `loadRecallEntries`, kept internal because the frozen q3b-ranker-floor benchmark imports it from dist. */
+export declare function loadRecallSearchEntries(hippoRoot: string, query: string, limit?: number, tenantId?: string, requestedScope?: string, explicitScopeMode?: 'exact' | 'additive', includeSuperseded?: boolean, originProjects?: OriginFilter, ownScope?: string): MemoryEntry[];
 export declare function loadRecallSearchEntriesFromDb(db: DatabaseSyncLike, query: string, options?: RecallSearchEntriesOptions): MemoryEntry[];
 /** Which rows the vector arm of hybrid search may add: the same tenant, scope and superseded rules as the lexical load. */
 export interface VectorCandidateSpec {