hippo-memory 1.68.0 → 1.70.0

package/dist/store/index-and-stats.d.ts

@@ -1,13 +1,16 @@
+import { type DatabaseSyncLike } from '../db/index.js';
 import type { HippoIndex, LegacyStats } from './rows.js';
 /** Load the derived index from SQLite. Read-only: index.json is only ever written by `rebuildIndex`. */
 export declare function loadIndex(hippoRoot: string): HippoIndex;
+/** The last recall's ids and its trace alone, for a caller that needs no index entry. */
+export declare function loadLastRecall(hippoRoot: string): Pick<HippoIndex, 'last_retrieval_ids' | 'last_trace_id'>;
 /**
  * Persist mutable index metadata. Entry rows themselves are derived from SQLite.
  *
  * `last_retrieval_ids` and `last_trace_id` commit in one transaction: callers fold a fresh trace id
  * into the index and rely on both keys moving together. index.json is left to `rebuildIndex`.
  */
-export declare function saveIndex(hippoRoot: string, index: HippoIndex): void;
+export declare function saveIndex(hippoRoot: string, index: Pick<HippoIndex, 'last_retrieval_ids' | 'last_trace_id'>): void;
 /**
  * Rebuild mirrors from SQLite, importing any legacy markdown files not already present.
  */
@@ -17,6 +20,8 @@ export declare function updateStats(hippoRoot: string, delta: {
     recalled?: number;
     forgotten?: number;
 }): void;
+/** updateStats on the caller's open store, so a loop of writes opens the store once. */
+export declare function updateStatsOn(db: DatabaseSyncLike, hippoRoot: string, delta: Parameters<typeof updateStats>[1]): void;
 export declare function updateStatsUnlessBusy(hippoRoot: string, delta: Parameters<typeof updateStats>[1], committed: string): void;
 export declare function loadStats(hippoRoot: string): LegacyStats;
 export declare function appendConsolidationRun(hippoRoot: string, run: {
@@ -36,6 +41,8 @@ export interface SessionDecayContext {
     /** Average interval between recent sleep cycles, in days. 0 if < 2 cycles. */
     avgSessionIntervalDays: number;
 }
+/** Timestamp of the latest consolidation run, or undefined when there is none. */
+export declare function lastConsolidationAt(db: DatabaseSyncLike): string | undefined;
 /**
  * Load the session decay context from the store.
  * Uses consolidation_runs timestamps to compute session intervals.

package/dist/store/index-and-stats.js

@@ -1,10 +1,11 @@
-import { closeHippoDb, setMeta, isSqliteBusy, pruneConsolidationRuns, getMeta } from '../db.js';
-import { RejectedValueError } from '../rejection.js';
-import { log } from '../log.js';
+import { closeHippoDb, withWriteScope, setMeta, isSqliteBusy, pruneConsolidationRuns, getMeta } from '../db/index.js';
+import { RejectedValueError } from './rejection.js';
+import { log } from '../util/log.js';
 import { audit } from './audit-event.js';
 import { stampOriginProjectForImport, upsertEntryRow } from './entry-row.js';
-import { buildIndexFromDb, syncMirrorFiles, writeIndexMirror, writeStatsMirror, buildStatsFromDb } from './mirrors.js';
+import { buildIndexFromDb, readLastRecall, syncMirrorFiles, writeIndexMirror, writeStatsMirror, buildStatsFromDb } from './mirrors.js';
 import { openStore, loadLegacyEntriesFromMarkdown } from './open.js';
+import { DAY_MS } from '../util/time.js';
 /** Load the derived index from SQLite. Read-only: index.json is only ever written by `rebuildIndex`. */
 export function loadIndex(hippoRoot) {
     const db = openStore(hippoRoot);
@@ -15,6 +16,16 @@ export function loadIndex(hippoRoot) {
         closeHippoDb(db);
     }
 }
+/** The last recall's ids and its trace alone, for a caller that needs no index entry. */
+export function loadLastRecall(hippoRoot) {
+    const db = openStore(hippoRoot);
+    try {
+        return readLastRecall(db);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 /**
  * Persist mutable index metadata. Entry rows themselves are derived from SQLite.
  *
@@ -24,19 +35,10 @@ export function loadIndex(hippoRoot) {
 export function saveIndex(hippoRoot, index) {
     const db = openStore(hippoRoot);
     try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
+        withWriteScope(db, 'save_index', () => {
             setMeta(db, 'last_retrieval_ids', JSON.stringify(index.last_retrieval_ids ?? []));
             setMeta(db, 'last_trace_id', index.last_trace_id ?? '');
-            db.exec('COMMIT');
-        }
-        catch (error) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* already rolled back; keep the original error */ }
-            throw error;
-        }
+        });
     }
     finally {
         closeHippoDb(db);
@@ -52,8 +54,7 @@ export function rebuildIndex(hippoRoot) {
         const existingIds = new Set(db.prepare(`SELECT id FROM memories`).all().map((row) => row.id));
         const legacyEntries = loadLegacyEntriesFromMarkdown(hippoRoot).filter((entry) => !existingIds.has(entry.id));
         if (legacyEntries.length > 0) {
-            db.exec('BEGIN IMMEDIATE');
-            try {
+            withWriteScope(db, 'rebuild_index', () => {
                 // Guard with per-row skip, like bootstrapLegacyStore: a stale markdown mirror could resurrect a
                 // rejected value here. Refusal audit is written inline because nothing rolls back on a skip.
                 let rejectedCount = 0;
@@ -66,7 +67,7 @@ export function rebuildIndex(hippoRoot) {
                     catch (err) {
                         if (err instanceof RejectedValueError) {
                             rejectedCount++;
-                            audit(db, 'reject_refusal', err.entryId, { digest: err.digest, reason: err.reason }, 'cli', err.tenantId);
+                            audit(db, 'reject_refusal', { targetId: err.entryId, metadata: { digest: err.digest, reason: err.reason }, actor: 'cli', tenantId: err.tenantId });
                             continue;
                         }
                         throw err;
@@ -75,15 +76,7 @@ export function rebuildIndex(hippoRoot) {
                 if (rejectedCount > 0) {
                     log.warn(`rebuildIndex: skipped ${rejectedCount} rejected value(s) found in legacy mirrors`);
                 }
-                db.exec('COMMIT');
-            }
-            catch (err) {
-                try {
-                    db.exec('ROLLBACK');
-                }
-                catch { /* ignore if no active txn */ }
-                throw err;
-            }
+            });
         }
         syncMirrorFiles(hippoRoot, db);
         const index = buildIndexFromDb(db);
@@ -97,30 +90,34 @@ export function rebuildIndex(hippoRoot) {
 export function updateStats(hippoRoot, delta) {
     const db = openStore(hippoRoot);
     try {
-        // One atomic statement per counter, and only for counters the caller
-        // named: the read-modify-write this replaces both lost increments to a
-        // concurrent writer and stamped stale values over the untouched two.
-        const increments = [
-            ['total_remembered', delta.remembered ?? 0],
-            ['total_recalled', delta.recalled ?? 0],
-            ['total_forgotten', delta.forgotten ?? 0],
-        ];
-        for (const [key, amount] of increments) {
-            if (amount === 0)
-                continue;
-            // Both binds are the same string: node:sqlite binds a JS number as REAL,
-            // which would store "1.0" into this TEXT column instead of "1".
-            db.prepare(`
-        INSERT INTO meta(key, value) VALUES(?, ?)
-        ON CONFLICT(key) DO UPDATE SET value = CAST(meta.value AS INTEGER) + CAST(? AS INTEGER)
-      `).run(key, String(amount), String(amount));
-        }
-        writeStatsMirror(hippoRoot, buildStatsFromDb(db));
+        updateStatsOn(db, hippoRoot, delta);
     }
     finally {
         closeHippoDb(db);
     }
 }
+/** updateStats on the caller's open store, so a loop of writes opens the store once. */
+export function updateStatsOn(db, hippoRoot, delta) {
+    // One atomic statement per counter, and only for counters the caller
+    // named: the read-modify-write this replaces both lost increments to a
+    // concurrent writer and stamped stale values over the untouched two.
+    const increments = [
+        ['total_remembered', delta.remembered ?? 0],
+        ['total_recalled', delta.recalled ?? 0],
+        ['total_forgotten', delta.forgotten ?? 0],
+    ];
+    for (const [key, amount] of increments) {
+        if (amount === 0)
+            continue;
+        // Both binds are the same string: node:sqlite binds a JS number as REAL,
+        // which would store "1.0" into this TEXT column instead of "1".
+        db.prepare(`
+      INSERT INTO meta(key, value) VALUES(?, ?)
+      ON CONFLICT(key) DO UPDATE SET value = CAST(meta.value AS INTEGER) + CAST(? AS INTEGER)
+    `).run(key, String(amount), String(amount));
+    }
+    writeStatsMirror(hippoRoot, buildStatsFromDb(db));
+}
 export function updateStatsUnlessBusy(hippoRoot, delta, committed) {
     try {
         updateStats(hippoRoot, delta);
@@ -155,7 +152,7 @@ export function appendConsolidationRun(hippoRoot, run) {
 export function countCreatedSinceLastSleep(hippoRoot, tenantId, now = new Date()) {
     const db = openStore(hippoRoot);
     try {
-        const dayAgo = new Date(now.getTime() - 86_400_000).toISOString();
+        const dayAgo = new Date(now.getTime() - DAY_MS).toISOString();
         const row = db.prepare(`SELECT COUNT(*) AS n FROM memories WHERE tenant_id = ?
          AND created > MAX(?, COALESCE((SELECT MAX(timestamp) FROM consolidation_runs), ''))`).get(tenantId, dayAgo);
         return row.n;
@@ -164,6 +161,12 @@ export function countCreatedSinceLastSleep(hippoRoot, tenantId, now = new Date()
         closeHippoDb(db);
     }
 }
+/** Timestamp of the latest consolidation run, or undefined when there is none. */
+export function lastConsolidationAt(db) {
+    // SAFETY: row's shape matches the single `timestamp` column named in the SELECT.
+    const row = db.prepare(`SELECT timestamp FROM consolidation_runs ORDER BY timestamp DESC, id DESC LIMIT 1`).get();
+    return row?.timestamp;
+}
 /**
  * Load the session decay context from the store.
  * Uses consolidation_runs timestamps to compute session intervals.
@@ -185,7 +188,7 @@ export function loadSessionDecayContext(hippoRoot) {
             totalInterval += timestamps[i] - timestamps[i - 1];
         }
         const avgMs = totalInterval / (timestamps.length - 1);
-        const avgDays = avgMs / (1000 * 60 * 60 * 24);
+        const avgDays = avgMs / DAY_MS;
         return { sleepCount, avgSessionIntervalDays: Math.max(0, avgDays) };
     }
     finally {

package/dist/store/index.d.ts

@@ -0,0 +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 { hasGroup, requireGroup } from './port.js';
+export * from './sqlite/store.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/store/index.js

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

package/dist/store/key-audit.d.ts

@@ -1,5 +1,5 @@
-import { type DatabaseSyncLike } from '../db.js';
-import type { KeyRevoke } from '../store-port.js';
+import { type DatabaseSyncLike } from '../db/index.js';
+import type { KeyRevoke } from './port.js';
 /** The revoke and its audit row commit together, so a failed audit write leaves the key live and the caller sees the error. */
 export declare function revokeKeyAt(db: DatabaseSyncLike, revoke: KeyRevoke): string;
 export declare function auditHighIdAt(db: DatabaseSyncLike): number;

package/dist/store/key-audit.js

@@ -1,8 +1,8 @@
 // hippo.db's half of the KeyAudit store group.
-import { NotFoundError } from '../api-errors.js';
-import { appendAuditEvent } from '../audit.js';
-import { revokeApiKey } from '../auth.js';
-import { withWriteScope } from '../db.js';
+import { NotFoundError } from '../core/api-errors.js';
+import { appendAuditEvent } from './audit.js';
+import { revokeApiKey } from './auth.js';
+import { withWriteScope } from '../db/index.js';
 import { selectApiKeyOwner } from './tenant-lookup.js';
 /** The revoke and its audit row commit together, so a failed audit write leaves the key live and the caller sees the error. */
 export function revokeKeyAt(db, revoke) {

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

@@ -1,9 +1,16 @@
-import { type AppendAuditOpts } from '../audit.js';
-import { type DatabaseSyncLike } from '../db.js';
-import type { KeyMint, SelfKeyMint } from '../store-port.js';
-/** The auth_create row a mint writes; the plaintext never reaches it. */
-export declare function createAuditOf({ key, actor, metadata }: KeyMint): AppendAuditOpts;
+import { type DatabaseSyncLike } from '../db/index.js';
+import type { KeyMint, SelfKeyMint } from './port.js';
 export declare function createKeyAt(db: DatabaseSyncLike, mint: KeyMint): void;
 /** IMMEDIATE takes the write lock before the count, so two mints for one owner cannot both see room under the cap. */
 export declare function createSelfKeyAt(db: DatabaseSyncLike, mint: SelfKeyMint): string[];
+/** One grant or ungrant of a restricted scope on a key of `tenantId`, and the actor of its audit row. */
+export interface ScopeGrantChange {
+    readonly tenantId: string;
+    readonly keyId: string;
+    readonly scope: string;
+    readonly op: 'auth_grant' | 'auth_ungrant';
+    readonly actor: string;
+}
+/** The key is checked under the write lock, and the change and its audit row commit together, so a failed audit write leaves the grants as they were. */
+export declare function changeScopeGrantAt(db: DatabaseSyncLike, { tenantId, keyId, scope, op, actor }: ScopeGrantChange): void;
 //# sourceMappingURL=key-writes.d.ts.map

package/dist/store/key-writes.js

@@ -1,9 +1,12 @@
 // hippo.db's half of the KeyWrites store group.
-import { appendAuditEvent } from '../audit.js';
-import { insertApiKey, listLiveOwnedKeyIds, revokeApiKey } from '../auth.js';
-import { withWriteScope } from '../db.js';
+import { BadRequestError, ConflictError, NotFoundError } from '../core/api-errors.js';
+import { appendAuditEvent } from './audit.js';
+import { grantScope, insertApiKey, listLiveOwnedKeyIds, revokeApiKey, ungrantScope } from './auth.js';
+import { withWriteScope } from '../db/index.js';
+import { isRestrictedScope } from './recall-scope.js';
+import { selectApiKeyOwner } from './tenant-lookup.js';
 /** The auth_create row a mint writes; the plaintext never reaches it. */
-export function createAuditOf({ key, actor, metadata }) {
+function createAuditOf({ key, actor, metadata }) {
     return { tenantId: key.tenantId, actor, op: 'auth_create', targetId: key.keyId, metadata };
 }
 export function createKeyAt(db, mint) {
@@ -27,4 +30,27 @@ export function createSelfKeyAt(db, mint) {
         return replaced;
     });
 }
+/** The key is checked under the write lock, and the change and its audit row commit together, so a failed audit write leaves the grants as they were. */
+export function changeScopeGrantAt(db, { tenantId, keyId, scope, op, actor }) {
+    withWriteScope(db, 'change_scope_grant', () => {
+        const row = selectApiKeyOwner(db, keyId);
+        if (!row || row.tenantId !== tenantId) {
+            throw new NotFoundError(`Unknown key_id: ${keyId}`);
+        }
+        if (op === 'auth_grant' && row.revokedAt) {
+            throw new ConflictError(`${keyId} is revoked; a grant on it would never apply`);
+        }
+        if (op === 'auth_grant' && /^personal:/i.test(scope)) {
+            throw new BadRequestError(`${scope} is a personal scope: only its owner reads it, and no grant can change that`);
+        }
+        if (!isRestrictedScope(scope)) {
+            throw new BadRequestError(`${scope} is not a restricted scope; it is already readable by default`);
+        }
+        if (op === 'auth_grant')
+            grantScope(db, keyId, scope);
+        else
+            ungrantScope(db, keyId, scope);
+        appendAuditEvent(db, { tenantId, actor, op, targetId: keyId, metadata: { scope } });
+    });
+}
 //# sourceMappingURL=key-writes.js.map

package/dist/store/ledger-turn.d.ts

@@ -0,0 +1,17 @@
+import type { DeliveryEventInput } from './delivery-recorder.js';
+import { type LastSent, type TokenSurface, type TokenUse } from './token-ledger.js';
+/** Stores one delivery event and returns its id, or null when the write failed. */
+export type DeliveryWrite = (input: DeliveryEventInput) => number | null;
+/** The token rows of one turn and the delivery event that follows them. */
+export interface LedgerTurn {
+    readonly uses: readonly TokenUse[];
+    /** Makes each row its own attempt: a failed one is reported here and the rest still run. Without it the first failure throws. */
+    readonly onRowError?: <E>(error: E) => void;
+    /** Runs after the rows with a writer on their connection, so the delivery event costs no second open. */
+    readonly delivery?: (write: DeliveryWrite) => void;
+}
+/** Books a turn's token rows, then its delivery event, on one connection. */
+export declare function recordLedgerTurn(hippoRoot: string, turn: LedgerTurn): void;
+/** What the session last sent on `surface`, or null, as lastSentState reads it. */
+export declare function lastSentOnSurface(hippoRoot: string, tenantId: string, sessionId: string | null | undefined, surface: TokenSurface): LastSent | null;
+//# sourceMappingURL=ledger-turn.d.ts.map

package/dist/store/ledger-turn.js

@@ -0,0 +1,27 @@
+import { lastSentState, recordTokenUse } from './token-ledger.js';
+import { onHandle } from './open.js';
+import { writeDeliveryEventOnHandle } from './recall-trace.js';
+/** Books a turn's token rows, then its delivery event, on one connection. */
+export function recordLedgerTurn(hippoRoot, turn) {
+    const { onRowError } = turn;
+    onHandle(hippoRoot, (db) => {
+        for (const use of turn.uses) {
+            if (onRowError === undefined) {
+                recordTokenUse(db, use);
+                continue;
+            }
+            try {
+                recordTokenUse(db, use);
+            }
+            catch (error) {
+                onRowError(error);
+            }
+        }
+        turn.delivery?.((input) => writeDeliveryEventOnHandle(db, input));
+    });
+}
+/** What the session last sent on `surface`, or null, as lastSentState reads it. */
+export function lastSentOnSurface(hippoRoot, tenantId, sessionId, surface) {
+    return onHandle(hippoRoot, (db) => lastSentState(db, tenantId, sessionId, surface));
+}
+//# sourceMappingURL=ledger-turn.js.map

package/dist/store/markdown.d.ts

@@ -1,4 +1,4 @@
-import { type MemoryEntry } from '../memory.js';
+import { type MemoryEntry } from '../core/memory.js';
 /**
  * Serialize a MemoryEntry to markdown with YAML frontmatter.
  */

package/dist/store/markdown.js

@@ -1,4 +1,5 @@
-import { dumpFrontmatter, parseFrontmatter } from '../yaml.js';
+import { FALLBACK_HALF_LIFE_DAYS, DEFAULT_SCHEMA_FIT } from '../core/memory.js';
+import { dumpFrontmatter, parseFrontmatter } from './yaml.js';
 /**
  * Serialize a MemoryEntry to markdown with YAML frontmatter.
  */
@@ -66,11 +67,11 @@ export function deserializeEntry(raw) {
         last_retrieved: String(data['last_retrieved'] ?? new Date().toISOString()),
         retrieval_count: Number(data['retrieval_count'] ?? 0),
         strength: Number(data['strength'] ?? 1.0),
-        half_life_days: Number(data['half_life_days'] ?? 7),
+        half_life_days: Number(data['half_life_days'] ?? FALLBACK_HALF_LIFE_DAYS),
         layer: data['layer'],
         tags: normalizeStringArray(data['tags']),
         emotional_valence: data['emotional_valence'] ?? 'neutral',
-        schema_fit: Number(data['schema_fit'] ?? 0.5),
+        schema_fit: Number(data['schema_fit'] ?? DEFAULT_SCHEMA_FIT),
         source: String(data['source'] ?? 'cli'),
         outcome_score: data['outcome_score'] === null || data['outcome_score'] === undefined ? null : Number(data['outcome_score']),
         outcome_positive: Number(data['outcome_positive'] ?? 0),

package/dist/store/mirrors.d.ts

@@ -1,18 +1,14 @@
-import { Layer, type MemoryEntry } from '../memory.js';
-import { openHippoDb } from '../db.js';
+import { Layer, type MemoryEntry } from '../core/memory.js';
+import { openHippoDb } from '../db/index.js';
 import { type TaskSnapshot, type SessionEvent, type HippoIndex, type LegacyStats } from './rows.js';
 export declare function layerDir(root: string, layer: Layer): string;
+/** Makes the mirror folders on a store's first open in this process; a writer makes its own folder if one goes missing later. */
 export declare function ensureMirrorDirectories(hippoRoot: string): void;
 export declare function writeActiveTaskMirror(hippoRoot: string, tenantId: string, snapshot: TaskSnapshot): void;
 export declare function removeActiveTaskMirror(hippoRoot: string, tenantId: string): void;
 export declare function writeRecentSessionMirror(hippoRoot: string, tenantId: string, events: SessionEvent[]): void;
 export declare function writeMarkdownMirror(hippoRoot: string, entry: MemoryEntry): void;
 export declare function removeEntryMirrors(hippoRoot: string, id: string): void;
-/**
- * Mirror paths for `id` still on disk, walked like `removeEntryMirrors`, so a failed purge
- * with no reaper to retry it can name the stuck file.
- */
-export declare function getExistingEntryMirrorPaths(hippoRoot: string, id: string): string[];
 /**
  * Best-effort mirror purge. Retries the unlink once (most failures are transient locks); the reaper only
  * scans `raw_archive`, so a non-raw id's second failure logs the leftover path(s) to delete by hand.
@@ -23,6 +19,8 @@ export declare function purgeMirrorBestEffort(hippoRoot: string, id: string, isR
 /** Derive the current `HippoIndex` from SQLite. Exported for `rebuildIndex`
  *  (the only index.json writer) and the longmemeval benchmark. */
 export declare function buildIndexFromDb(db: ReturnType<typeof openHippoDb>): HippoIndex;
+/** The last recall's ids and its trace, the two meta keys saveIndex writes together. */
+export declare function readLastRecall(db: ReturnType<typeof openHippoDb>): Pick<HippoIndex, 'last_retrieval_ids' | 'last_trace_id'>;
 export declare function buildStatsFromDb(db: ReturnType<typeof openHippoDb>): LegacyStats;
 /** Write the `index.json` mirror file for an already-derived index. Exported for
  *  `rebuildIndex` (the only index.json writer) and the longmemeval benchmark. */

package/dist/store/mirrors.js

@@ -1,25 +1,25 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import { Layer } from '../memory.js';
-import { dumpFrontmatter } from '../yaml.js';
-import { getMeta } from '../db.js';
-import { log } from '../log.js';
+import { Layer } from '../core/memory.js';
+import { dumpFrontmatter } from './yaml.js';
+import { getMeta } from '../db/index.js';
+import { oncePerStore } from '../db/connect.js';
+import { errorMessage, log } from '../util/log.js';
 import { parseJsonArray, INDEX_VERSION, parseLastTraceId, MEMORY_SELECT_COLUMNS, rowToEntry, rowToMemoryConflict, } from './rows.js';
 import { serializeEntry } from './markdown.js';
+const SCORE_DECIMALS = 3;
 export function layerDir(root, layer) {
     return path.join(root, layer);
 }
+// Owner-only wherever a mirror folder is made, at open or by a writer that finds it gone.
+const MIRROR_FOLDER = { recursive: true, mode: 0o700 };
+/** Makes the mirror folders on a store's first open in this process; a writer makes its own folder if one goes missing later. */
 export function ensureMirrorDirectories(hippoRoot) {
-    const dirs = [
-        hippoRoot,
-        path.join(hippoRoot, 'buffer'),
-        path.join(hippoRoot, 'episodic'),
-        path.join(hippoRoot, 'semantic'),
-        path.join(hippoRoot, 'conflicts'),
-    ];
-    for (const dir of dirs) {
-        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-    }
+    oncePerStore(hippoRoot, 'mirror-folders', () => {
+        for (const sub of ['buffer', 'episodic', 'semantic', 'conflicts']) {
+            fs.mkdirSync(path.join(hippoRoot, sub), MIRROR_FOLDER);
+        }
+    });
 }
 // Tenant-scoped mirror file paths. The single-tenant 'default' deployment
 // keeps the original `active-task.md` / `recent-session.md` filenames for
@@ -61,7 +61,7 @@ export function writeActiveTaskMirror(hippoRoot, tenantId, snapshot) {
     if (snapshot.session_id) {
         body.push(`## Session`, snapshot.session_id, '');
     }
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.mkdirSync(path.dirname(filePath), MIRROR_FOLDER);
     fs.writeFileSync(filePath, `${fm}\n\n${body.join('\n')}`, 'utf8');
 }
 export function removeActiveTaskMirror(hippoRoot, tenantId) {
@@ -99,12 +99,12 @@ export function writeRecentSessionMirror(hippoRoot, tenantId, events) {
         lines.push(`- [${event.created_at}] (${event.event_type}) ${event.content}`);
     }
     lines.push('');
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.mkdirSync(path.dirname(filePath), MIRROR_FOLDER);
     fs.writeFileSync(filePath, `${fm}\n\n${lines.join('\n')}`, 'utf8');
 }
 function writeConflictMirrors(hippoRoot, conflicts) {
     const conflictDir = path.join(hippoRoot, 'conflicts');
-    fs.mkdirSync(conflictDir, { recursive: true });
+    fs.mkdirSync(conflictDir, MIRROR_FOLDER);
     const keep = new Set();
     for (const conflict of conflicts) {
         const filename = `conflict_${conflict.id}.md`;
@@ -125,7 +125,7 @@ function writeConflictMirrors(hippoRoot, conflicts) {
             `- Memory A: ${conflict.memory_a_id}`,
             `- Memory B: ${conflict.memory_b_id}`,
             `- Reason: ${conflict.reason}`,
-            `- Score: ${conflict.score.toFixed(3)}`,
+            `- Score: ${conflict.score.toFixed(SCORE_DECIMALS)}`,
             `- Status: ${conflict.status}`,
             '',
         ].join('\n');
@@ -142,7 +142,7 @@ function writeConflictMirrors(hippoRoot, conflicts) {
 export function writeMarkdownMirror(hippoRoot, entry) {
     removeEntryMirrors(hippoRoot, entry.id);
     const dir = layerDir(hippoRoot, entry.layer);
-    fs.mkdirSync(dir, { recursive: true });
+    fs.mkdirSync(dir, MIRROR_FOLDER);
     fs.writeFileSync(path.join(dir, `${entry.id}.md`), serializeEntry(entry), 'utf8');
 }
 // Every layer, Trace included: `writeMarkdownMirror` writes any layer, and a stale trace mirror
@@ -159,7 +159,7 @@ export function removeEntryMirrors(hippoRoot, id) {
  * Mirror paths for `id` still on disk, walked like `removeEntryMirrors`, so a failed purge
  * with no reaper to retry it can name the stuck file.
  */
-export function getExistingEntryMirrorPaths(hippoRoot, id) {
+function getExistingEntryMirrorPaths(hippoRoot, id) {
     // Layer list kept in lockstep with removeEntryMirrors.
     return [Layer.Buffer, Layer.Episodic, Layer.Semantic, Layer.Trace]
         .map((layer) => path.join(layerDir(hippoRoot, layer), `${id}.md`))
@@ -182,7 +182,7 @@ export function purgeMirrorBestEffort(hippoRoot, id, isRaw, logPrefix) {
             return true;
         }
         catch (secondErr) {
-            const msg = secondErr instanceof Error ? secondErr.message : String(secondErr);
+            const msg = errorMessage(secondErr);
             if (isRaw) {
                 log.error(`${logPrefix}: mirror cleanup failed for ${id} (will retry via reaper on next open): ${msg}`);
             }
@@ -217,14 +217,16 @@ export function buildIndexFromDb(db) {
             pinned: Boolean(row.pinned),
         };
     }
+    return { version: INDEX_VERSION, entries, ...readLastRecall(db) };
+}
+/** The last recall's ids and its trace, the two meta keys saveIndex writes together. */
+export function readLastRecall(db) {
     // Read both lockstep keys in ONE statement: two autocommit SELECTs could straddle a concurrent
     // saveIndex and hand back a mismatched last_retrieval_ids / last_trace_id pair.
     // SAFETY: lockstepRows' shape matches the key/value columns named above.
     const lockstepRows = db.prepare(`SELECT key, value FROM meta WHERE key IN ('last_retrieval_ids', 'last_trace_id')`).all();
     const lockstep = new Map(lockstepRows.map((r) => [r.key, r.value]));
     return {
-        version: INDEX_VERSION,
-        entries,
         last_retrieval_ids: parseJsonArray(lockstep.get('last_retrieval_ids') ?? '[]'),
         last_trace_id: parseLastTraceId(lockstep.get('last_trace_id') ?? ''),
     };
@@ -250,7 +252,19 @@ export function writeIndexMirror(hippoRoot, index) {
     mirrorBestEffort('index.json', () => fs.writeFileSync(path.join(hippoRoot, 'index.json'), JSON.stringify(index, null, 2), 'utf8'));
 }
 export function writeStatsMirror(hippoRoot, stats) {
-    mirrorBestEffort('stats.json', () => fs.writeFileSync(path.join(hippoRoot, 'stats.json'), JSON.stringify(stats, null, 2), 'utf8'));
+    mirrorBestEffort('stats.json', () => overwriteInPlace(path.join(hippoRoot, 'stats.json'), JSON.stringify(stats, null, 2)));
+}
+// A truncate waits for the file's last write to reach the disk, so a file rewritten on every recall keeps its blocks.
+function overwriteInPlace(file, text) {
+    const bytes = Buffer.from(text, 'utf8');
+    const fd = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_CREAT, 0o666);
+    try {
+        fs.writeSync(fd, bytes, 0, bytes.length, 0);
+        fs.ftruncateSync(fd, bytes.length);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
 }
 /** Mirrors are derived from SQLite and written after COMMIT, so a failed write warns instead of failing a committed change. */
 export function mirrorBestEffort(what, write) {
@@ -258,7 +272,7 @@ export function mirrorBestEffort(what, write) {
         write();
     }
     catch (err) {
-        log.warn(`${what} not refreshed (${err instanceof Error ? err.message : String(err)}); the database write succeeded`);
+        log.warn(`${what} not refreshed (${errorMessage(err)}); the database write succeeded`);
     }
 }
 export function syncMirrorFiles(hippoRoot, db) {