hippo-memory 1.72.0 → 2.1.0

package/dist/api/sleep/dormant.js

@@ -0,0 +1,64 @@
+// Dormant memories: list, restore, forget and check.
+import { ConflictError, NotFoundError } from '../../core/api-errors.js';
+import { stampOriginProject } from '../../store/entry-row.js';
+import { strengthAblation } from '../../core/ablation.js';
+import { createMemory, calculateStrength } from '../../core/memory.js';
+import { configOf } from '../config-of.js';
+import { canTouchScope, personalScopeOf } from '../../core/recall-scope.js';
+/**
+ * A tenant's dormant memories (src/store/dormant.ts): what sleep moved out of active memory when `dormant.enabled` is
+ * on. Newest first;
+ * `opts.query` keeps rows containing every term (case-insensitive). */
+export function listDormant(ctx, opts = {}) {
+    return ctx.store.dormant.list(ctx.tenantId, personalScopeOf(ctx.actor), opts);
+}
+/**
+ * Restores a dormant memory as if just recalled, with a full half-life; a row set aside by audit repair returns
+ * `verified`.
+ * Throws if the tenant has no such dormant id or a live memory holds it, and RejectedValueError if the value was since
+ * rejected (the dormant copy stays).
+ */
+export async function restoreDormant(ctx, id) {
+    const outcome = await ctx.store.dormant.restore(ctx.tenantId, {
+        id,
+        actor: ctx.actor.subject,
+        inReach: (scope) => canTouchScope(ctx.actor, scope),
+        revive: (snapshot, now) => reviveSnapshot(ctx, snapshot, now),
+    });
+    if (outcome.status === 'missing')
+        throw new NotFoundError(`dormant memory not found: ${id}`);
+    if (outcome.status === 'active') {
+        throw new ConflictError(`memory ${id} is already active; forget it before restoring its dormant copy`);
+    }
+    return outcome.entry;
+}
+function reviveSnapshot(ctx, dormant, now) {
+    // A snapshot can predate a field added later: createMemory supplies defaults, then the snapshot overrides every field
+    // it carries.
+    // The placeholder content only meets createMemory's minimum length, so a legacy row under 3 chars still restores.
+    const revived = {
+        ...createMemory('dormant snapshot defaults', { baseHalfLifeDays: configOf(ctx).defaultHalfLifeDays }),
+        ...dormant.entry,
+        last_retrieved: now.toISOString(),
+    };
+    if (dormant.reason === 'quality-repair')
+        revived.confidence = 'verified';
+    return stampOriginProject(ctx.hippoRoot, {
+        ...revived,
+        strength: calculateStrength(revived, now, { ablation: strengthAblation() }),
+    });
+}
+/**
+ * Permanently deletes a dormant memory, the explicit "forget it for good"; throws when the tenant has no dormant memory
+ * with that id.
+ */
+export async function forgetDormant(ctx, id) {
+    const forgotten = await ctx.store.dormant.forget(ctx.tenantId, personalScopeOf(ctx.actor), id, ctx.actor.subject);
+    if (!forgotten)
+        throw new NotFoundError(`dormant memory not found: ${id}`);
+}
+/** Whether the tenant holds a dormant memory with this id that the caller may touch (for "not found" hints). */
+export function isDormant(ctx, id) {
+    return ctx.store.dormant.holds(ctx.tenantId, personalScopeOf(ctx.actor), id);
+}
+//# sourceMappingURL=dormant.js.map

package/dist/api/{learn.d.ts → sleep/learn.d.ts}

@@ -1,5 +1,5 @@
-import { type InvalidationOptions, type InvalidationResult, type InvalidationTarget } from '../learn/invalidation.js';
-import type { Context } from './types.js';
+import { type InvalidationOptions, type InvalidationResult, type InvalidationTarget } from '../../learn/invalidation.js';
+import type { Context, ContextWith } from '../types.js';
 /** How a surface writes what it learns. */
 export interface LearnProfile {
     readonly tags: readonly string[];
@@ -28,8 +28,9 @@ export interface LearnResult {
     }>;
 }
 /** Learn from `repoPath`'s last `days` of commits into the caller's tenant. Host admin only. */
-export declare function learn(ctx: Context, opts: LearnOpts): LearnResult;
+export declare function learn(ctx: ContextWith<'lessonWrites'>, opts: LearnOpts): Promise<LearnResult>;
 export type { InvalidationOptions, InvalidationResult, InvalidationTarget };
-/** `hippo invalidate`: weakens the caller's tenant's memories that reference `target.from`, or only the one `options.onlyId` names. */
+/** `hippo invalidate`: weakens the caller's tenant's memories that
+ * reference `target.from`, or only the one `options.onlyId` names. */
 export declare function invalidateMemories(ctx: Context, target: InvalidationTarget, options: InvalidationOptions): InvalidationResult;
 //# sourceMappingURL=learn.d.ts.map

package/dist/api/sleep/learn.js

@@ -0,0 +1,138 @@
+// Git auto-learn: fix/revert/bug commit subjects become memories.
+// `hippo learn`, init, sleep and MCP hippo_learn share it.
+import { ForbiddenError } from '../../core/api-errors.js';
+import { fetchGitLog, extractLessons, partitionLessons, isGitRepo } from '../../learn/autolearn.js';
+import { configOf } from '../config-of.js';
+import { embedMemory } from '../../search/embed-memories.js';
+import { extractInvalidationTarget, invalidateMatching, invalidateMatchingAmong, } from '../../learn/invalidation.js';
+import { createMemory, Layer, schemaFitFrom, schemaFitSourceOf } from '../../core/memory.js';
+import { extractPathTags } from '../../search/path-context.js';
+import { canReadScope, personalScopeOf } from '../../core/recall-scope.js';
+import { duplicateKey, longestWord, storedTextKeys } from '../../util/same-text.js';
+// SHORTCUT: two profiles keep each surface's rows as they were; fold MCP onto the CLI profile once it may invalidate.
+export const CLI_LEARN = Object.freeze({
+    tags: Object.freeze(['error', 'git-learned']),
+    source: 'git-learn',
+    full: true,
+});
+export const MCP_LEARN = Object.freeze({
+    tags: Object.freeze(['git-learned']),
+    source: 'git',
+    full: false,
+});
+/** Learn from `repoPath`'s last `days` of commits into the caller's tenant. Host admin only. */
+export async function learn(ctx, opts) {
+    // It reads the host's own git history, which belongs to the host, not to the caller's tenant.
+    if (!ctx.actor.hostAdmin)
+        throw new ForbiddenError('hippo_learn requires a host admin');
+    const none = { added: 0, skipped: 0, rejected: 0, lowInfo: 0, invalidations: [] };
+    if (!isGitRepo(opts.repoPath))
+        return { status: 'not-a-repo', ...none };
+    const gitLog = fetchGitLog(opts.repoPath, opts.days);
+    if (!gitLog.trim())
+        return { status: 'no-commits', ...none };
+    const config = configOf(ctx);
+    const parsed = extractLessons(gitLog, config.gitLearnPatterns);
+    if (parsed.length === 0)
+        return { status: 'no-lessons', ...none };
+    // The gate filters the loop input, so a dropped lesson neither stores nor invalidates; docs/decisions
+    // git-learn-gate-placement says why.
+    const { kept, dropped } = partitionLessons(parsed);
+    return { status: 'scanned', lowInfo: dropped.length, ...await writeLessons(ctx, kept, opts, config) };
+}
+/** Writes `queued` in one transaction; a refused lesson is dropped from `live` and `keys` and must not abort the rest
+ * of the git-log scan. */
+async function landLessons(batch, queued) {
+    if (queued.length === 0)
+        return;
+    const { ctx, writes, live, keys, counts } = batch;
+    const written = new Set(await writes.writeSkippingRejected(queued.map((q) => q.entry), ctx.actor.subject));
+    const landed = [];
+    for (const { entry, key } of queued) {
+        if (written.has(entry.id)) {
+            landed.push(entry);
+            continue;
+        }
+        counts.rejected++;
+        keys.delete(key);
+        const at = live.indexOf(entry);
+        if (at !== -1)
+            live.splice(at, 1);
+    }
+    counts.added += landed.length;
+    if (!batch.full)
+        return;
+    if (landed.length > 0)
+        await writes.bumpRemembered(landed.length);
+    for (const entry of landed)
+        void embedMemory(ctx.hippoRoot, entry, undefined, ctx.store);
+}
+/** The duplicate keys a batch skips: every readable row's with
+ * `existing`, else only the rows holding a lesson's longest word. */
+async function knownKeys(ctx, writes, lessons, existing) {
+    return storedTextKeys(existing ?? (await writes.textsHoldingWords(ctx.tenantId, lessons.map(longestWord), personalScopeOf(ctx.actor))));
+}
+function newLessonMemory(lesson, profile, inputs) {
+    const { tenantId, config, fitSource, pathTags } = inputs;
+    const entry = createMemory(lesson, {
+        layer: Layer.Episodic,
+        tags: [...profile.tags],
+        source: profile.source,
+        confidence: 'observed',
+        schemaFit: fitSource && schemaFitFrom(lesson, [...profile.tags], fitSource),
+        tenantId,
+        baseHalfLifeDays: config.defaultHalfLifeDays,
+    });
+    for (const tag of pathTags)
+        if (!entry.tags.includes(tag))
+            entry.tags.push(tag);
+    return entry;
+}
+async function writeLessons(ctx, lessons, opts, config) {
+    const { tenantId } = ctx;
+    const { profile } = opts;
+    const store = ctx.store;
+    const writes = store.lessonWrites;
+    // One read serves the batch: invalidation matches against `live`,
+    // which follows every write below, as a reload per lesson did.
+    const live = profile.full ? await writes.tenantEntries(tenantId) : [];
+    // Schema fit needs every row; without it, only rows holding a lesson's longest word can be its copy. Learn is
+    // host-admin only, so both read what an admin can.
+    const existing = profile.full ? live.filter((e) => e.scope == null || canReadScope(ctx.actor, e.scope)) : undefined;
+    // Each lesson is scored against `existing` as it was before the batch, so its tag counts and texts are read once.
+    const fitSource = existing && schemaFitSourceOf(existing);
+    const batch = {
+        ctx, writes, live, keys: await knownKeys(ctx, writes, lessons, existing), full: profile.full,
+        counts: { added: 0, skipped: 0, rejected: 0, invalidations: [] },
+    };
+    const pathTags = profile.full ? extractPathTags(opts.repoPath) : [];
+    // Lessons queue and land in one transaction; an invalidation reads the store, so it flushes the queue first.
+    const queue = [];
+    for (const lesson of lessons) {
+        const key = duplicateKey(lesson);
+        if (batch.keys.has(key)) {
+            batch.counts.skipped++;
+            continue;
+        }
+        const target = profile.full ? extractInvalidationTarget(lesson) : null;
+        if (target) {
+            await landLessons(batch, queue.splice(0));
+            const { invalidated } = await invalidateMatchingAmong(store, live, target, tenantId);
+            if (invalidated > 0)
+                batch.counts.invalidations.push({ from: target.from, count: invalidated });
+        }
+        const entry = newLessonMemory(lesson, profile, { tenantId, config, fitSource, pathTags });
+        queue.push({ entry, key });
+        if (profile.full)
+            live.push(entry);
+        batch.keys.add(key);
+    }
+    await landLessons(batch, queue.splice(0));
+    return batch.counts;
+}
+/** `hippo invalidate`: weakens the caller's tenant's memories that
+ * reference `target.from`, or only the one `options.onlyId` names. */
+export function invalidateMemories(ctx, target, options) {
+    return invalidateMatching(ctx.hippoRoot, target, ctx.tenantId, options);
+}
+//# sourceMappingURL=learn.js.map

package/dist/api/sleep/sleep-run.d.ts

@@ -0,0 +1,38 @@
+import { auditMemories } from '../../core/memory-audit.js';
+import { autoShare } from '../../sharing/share.js';
+import { runConsolidation } from '../../consolidate/sleep.js';
+import { loadConfig } from '../../core/config.js';
+import { deduplicateStore } from '../../consolidate/dedupe.js';
+import { computeAmbientState } from '../../core/ambient.js';
+import { type ExtractResult } from '../../graph/extract.js';
+import type { MemoryEntry } from '../../core/memory.js';
+import type { ContextWith } from '../types.js';
+import type { Consolidation, Objects } from '../../store/port.js';
+import type { SleepOpts, SleepResult } from './sleep.js';
+/** Test-only seam: `runSleep` overrides force a phase to throw into emitSleepAudit's `partial: true` row; production
+ * never sets them. */
+export interface SleepPhases {
+    consolidate: typeof runConsolidation;
+    deduplicateStore: typeof deduplicateStore;
+    auditMemories: typeof auditMemories;
+    autoShare: typeof autoShare;
+    loadAllEntries: (store: Consolidation) => MemoryEntry[];
+    computeAmbientState: typeof computeAmbientState;
+    loadConfig: typeof loadConfig;
+    loadPendingExtractionTenants: (store: Consolidation) => DirtyTenantSnapshot['dirtyTenants'];
+    extractGraph: (objects: Objects, hippoRoot: string, tenantId: string) => ExtractResult | Promise<ExtractResult>;
+}
+interface DirtyTenantSnapshot {
+    dirtyTenants: {
+        tenantId: string;
+        maxPendingId: number;
+    }[];
+    error: string | null;
+}
+/** The groups one sleep runs on: hippo.db's own files, the audit pass and the graph's objects. */
+type SleepContext = ContextWith<'auditMaintenance' | 'objects' | 'localFiles'>;
+/** `sleep` with its phase dependencies overridable; tests pass
+ * stubs here, so the seam never touches the public `SleepOpts`. */
+export declare function runSleep(ctx: SleepContext, opts: SleepOpts, overrides?: Partial<SleepPhases>): Promise<SleepResult>;
+export {};
+//# sourceMappingURL=sleep-run.d.ts.map

package/dist/api/{sleep-run.js → sleep/sleep-run.js}

@@ -1,66 +1,68 @@
 // The sleep pipeline behind `sleep`, with its phase dependencies injectable; kept out of the package root.
-import { loadAllEntries } from '../store/entry-reads.js';
-import { memoriesBackingObjects } from '../store/delete-and-batch.js';
-import { reportAuditWriteFailure } from '../store/audit.js';
-import { auditMemories } from '../core/memory-audit.js';
-import { sqliteSyncStore } from '../store/sqlite/store.js';
-import { AUTO_SHARE_MIN_SCORE, autoShare } from '../sharing/share.js';
-import { consolidate } from '../consolidate/sleep.js';
-import { failedUnitOf } from '../store/delete-and-batch.js';
-import { loadConfig } from '../core/config.js';
-import { deduplicateStore } from '../consolidate/dedupe.js';
-import { computeAmbientState } from '../core/ambient.js';
-import { loadPendingExtractionTenants, markPendingProcessedUpTo } from '../store/graph-queue.js';
-import { extractGraphChunked } from '../graph/extract.js';
-import { removeAuditErrors } from './audit.js';
-import { errorMessage } from '../util/log.js';
+import { auditMemories } from '../../core/memory-audit.js';
+import { AUTO_SHARE_MIN_SCORE, autoShare } from '../../sharing/share.js';
+import { runConsolidation } from '../../consolidate/sleep.js';
+import { loadConfig } from '../../core/config.js';
+import { deduplicateStore } from '../../consolidate/dedupe.js';
+import { computeAmbientState } from '../../core/ambient.js';
+import { extractGraphChunked } from '../../graph/extract.js';
+import { objectsOf } from '../objects/objects.js';
+import { removeAuditErrors } from '../auth/audit.js';
+import { errorMessage } from '../../util/log.js';
 const DEFAULT_SLEEP_PHASES = {
-    consolidate,
+    consolidate: runConsolidation,
     deduplicateStore,
     auditMemories,
     autoShare,
-    loadAllEntries,
+    loadAllEntries: (store) => store.allEntries(),
     computeAmbientState,
     loadConfig,
-    loadPendingExtractionTenants,
+    loadPendingExtractionTenants: (store) => store.dirtyGraphTenants(),
     extractGraph: extractGraphChunked,
 };
-/** `sleep` with its phase dependencies overridable; tests pass stubs here, so the seam never touches the public `SleepOpts`. */
+/** `sleep` with its phase dependencies overridable; tests pass
+ * stubs here, so the seam never touches the public `SleepOpts`. */
 export async function runSleep(ctx, opts, overrides = {}) {
     const dryRun = Boolean(opts.dryRun);
     const phases = { ...DEFAULT_SLEEP_PHASES, ...overrides };
-    // Phase counters for the consolidate audit emit (in finally), accumulated per phase so a partial failure still reports what got done.
+    // Phase counters for the consolidate audit emit (in finally), accumulated per phase so a partial failure still
+    // reports what got done.
     const counts = { consolidation: 0, dedup: 0, auditDeleted: 0, ambient: 0 };
     let phaseError = null;
     try {
         return await runSleepPhases(ctx, opts, phases, counts);
     }
     catch (err) {
-        // SAFETY: phaseError is only read via phaseError.message / (phaseError !== null) below, safe even if a non-Error was thrown;
-        // this mirrors the lenient (err as Error) pattern used through this catch chain.
+        // SAFETY: phaseError is only read via phaseError.message / (phaseError !== null) below, safe even if a non-Error
+        // was thrown; this mirrors the lenient (err as Error) pattern used through this catch chain.
         phaseError = err;
         throw err;
     }
     finally {
-        emitSleepAudit(ctx, opts, dryRun, counts, phaseError);
+        await emitSleepAudit(ctx, opts, dryRun, counts, phaseError);
     }
 }
 async function runSleepPhases(ctx, opts, phases, counts) {
     const dryRun = Boolean(opts.dryRun);
     const snapshot = snapshotDirtyTenants(ctx, phases, dryRun);
     // Phase 1: Consolidation.
-    const consolidateResult = await phases.consolidate(ctx.hippoRoot, { dryRun });
+    const local = ctx.store.localFiles;
+    const consolidateResult = await phases.consolidate(local, { dryRun });
     counts.consolidation = consolidateResult.semanticCreated + consolidateResult.merged;
     const result = sleepResultFrom(consolidateResult, dryRun);
-    // One read after consolidation serves dedup, the audit and ambient: dedup reports every row it deletes, so later phases subtract instead of reading again.
-    const loaded = { entries: phases.loadAllEntries(ctx.hippoRoot), backing: memoriesBackingObjects(ctx.hippoRoot) };
+    // Consolidate's own read predates its writes, so it cannot stand in for this one. One read after consolidation serves
+    // dedup, the audit and ambient: dedup reports every row it deletes, so later phases subtract.
+    const loaded = {
+        entries: phases.loadAllEntries(local.consolidation),
+        backing: local.consolidation.objectBackedIds(),
+    };
     // Phase 2: Dedup (post-consolidate near-duplicate cleanup).
-    const dedupResult = phases.deduplicateStore(ctx.hippoRoot, { dryRun, actor: ctx.actor.subject, loaded });
+    const dedupResult = phases.deduplicateStore(local.consolidation, { dryRun, actor: ctx.actor.subject, loaded });
     counts.dedup = dedupResult.removed;
     if (dedupResult.removed > 0)
         result.deduped = dedupSummary(dedupResult);
     // Phase 3: Quality audit (remove junk, report warnings; a dry run skips rows earlier phases would remove).
-    const audited = runQualityAudit(ctx, phases, { dryRun, consolidateResult, dedupResult, result, loaded });
+    const audited = await runQualityAudit(ctx, phases, { dryRun, consolidateResult, dedupResult, result, loaded });
     counts.auditDeleted = audited.removed;
     if (dryRun)
         return result;
@@ -78,7 +80,7 @@ function snapshotDirtyTenants(ctx, phases, dryRun) {
     const snapshot = { dirtyTenants: [], error: null };
     if (!dryRun) {
         try {
-            snapshot.dirtyTenants = phases.loadPendingExtractionTenants(ctx.hippoRoot);
+            snapshot.dirtyTenants = phases.loadPendingExtractionTenants(ctx.store.localFiles.consolidation);
         }
         catch (snapErr) {
             snapshot.error = errorMessage(snapErr);
@@ -116,18 +118,23 @@ function dedupSummary(dedupResult) {
         crossDups,
     };
 }
-/** `removed` counts audit errors deleted (or that would be under dryRun); `remaining` is what the audit read, less the rows it deleted. */
-function runQualityAudit(ctx, phases, options) {
+/** `removed` counts audit errors deleted (or that would be under dryRun); `remaining` is what the audit read, less the
+ * rows it deleted. */
+async function runQualityAudit(ctx, phases, options) {
     const { dryRun, consolidateResult, dedupResult, result, loaded } = options;
-    // The load followed consolidation, so only a dry run still holds the rows consolidation would remove; dedup's pairs are gone or would be.
-    const planned = new Set([...(dryRun ? consolidateResult.removedIds ?? [] : []), ...dedupResult.pairs.map((p) => p.removed)]);
+    // The load followed consolidation, so only a dry run still holds the rows consolidation would remove; dedup's pairs
+    // are gone or would be.
+    const planned = new Set([
+        ...(dryRun ? (consolidateResult.removedIds ?? []) : []),
+        ...dedupResult.pairs.map((p) => p.removed),
+    ]);
     const allEntries = loaded.entries.filter((e) => !planned.has(e.id));
     const auditOut = phases.auditMemories(allEntries, loaded.backing);
     if (auditOut.issues.length === 0)
         return { removed: 0, remaining: allEntries };
     const errors = auditOut.issues.filter((i) => i.severity === 'error');
     const warnings = auditOut.issues.filter((i) => i.severity === 'warning');
-    const gone = dryRun ? errors.map((issue) => issue.memoryId) : removeAuditErrors(ctx, 'sleep-audit', errors);
+    const gone = dryRun ? errors.map((issue) => issue.memoryId) : await removeAuditErrors(ctx, 'sleep-audit', errors);
     const removed = gone.length;
     const deleted = new Set(gone);
     if (removed > 0 || warnings.length > 0) {
@@ -139,7 +146,7 @@ function runQualityAudit(ctx, phases, options) {
     return { removed, remaining: allEntries.filter((e) => !deleted.has(e.id)) };
 }
 function shareOnSleep(ctx, phases, result) {
-    const sleepConfig = phases.loadConfig(ctx.hippoRoot);
+    const sleepConfig = ctx.config ?? phases.loadConfig(ctx.hippoRoot);
     if (!sleepConfig.autoShareOnSleep)
         return;
     // Both skip counters are surfaced so the secret veto and the rejection tombstone are observable, not silent.
@@ -157,7 +164,7 @@ function shareOnSleep(ctx, phases, result) {
 }
 /** Returns the ambient total the audit row reports: 0 when ambient is off or no current row is left. */
 function summarizeAmbient(ctx, phases, result, loaded) {
-    const postSleepConfig = phases.loadConfig(ctx.hippoRoot);
+    const postSleepConfig = ctx.config ?? phases.loadConfig(ctx.hippoRoot);
     if (!postSleepConfig.ambient.enabled)
         return 0;
     const postSleepEntries = loaded.filter((e) => !e.superseded_by);
@@ -193,10 +200,11 @@ async function drainGraphQueue(ctx, phases, snapshot, result) {
         ];
     }
 }
-/** Rebuilds one dirty tenant's graph into `rebuilt` and drains its queue; a failure is a detail line and the tenant stays pending. */
+/** Rebuilds one dirty tenant's graph into `rebuilt` and drains its
+ * queue; a failure is a detail line and the tenant stays pending. */
 async function rebuildDirtyTenant(ctx, phases, dirty, rebuilt, result) {
     try {
-        const ext = await phases.extractGraph(ctx.hippoRoot, dirty.tenantId);
+        const ext = await phases.extractGraph(objectsOf(ctx), ctx.hippoRoot, dirty.tenantId);
         // Count the rebuild as soon as it succeeds — it happened regardless of
         // the drain-mark below.
         rebuilt.tenants += 1;
@@ -210,7 +218,7 @@ async function rebuildDirtyTenant(ctx, phases, dirty, rebuilt, result) {
         }
         // Watermark drain: only items enqueued before this rebuild started are marked; later arrivals stay pending.
         // Marked only after the last chunk, so a run stopped between chunks leaves the tenant for the next one.
-        markPendingProcessedUpTo(ctx.hippoRoot, dirty.tenantId, dirty.maxPendingId);
+        ctx.store.localFiles.consolidation.markGraphDrained(dirty.tenantId, dirty.maxPendingId);
     }
     catch (tenantErr) {
         result.details = [
@@ -220,8 +228,8 @@ async function rebuildDirtyTenant(ctx, phases, dirty, rebuilt, result) {
     }
 }
 // One 'consolidate' row per sleep, emitted from finally so a partial failure still reports what got done.
-// Its own handle; an audit failure is logged and never replaces the original phase error.
-function emitSleepAudit(ctx, opts, dryRun, counts, phaseError) {
+// An audit failure is logged and never replaces the original phase error.
+async function emitSleepAudit(ctx, opts, dryRun, counts, phaseError) {
     try {
         // Tagged '__host__' because sleep is host-wide; the actor still names the operator who ran it.
         const sleepAuditMetadata = {
@@ -236,11 +244,12 @@ function emitSleepAudit(ctx, opts, dryRun, counts, phaseError) {
         };
         if (phaseError)
             sleepAuditMetadata.errorMessage = phaseError.message;
-        // A flush stopped between chunks names the unit it would have committed next, so a unit that fails every night can be found.
-        const nextUnitIds = failedUnitOf(phaseError);
+        // A flush stopped between chunks names the unit it would have
+        // committed next, so a unit that fails every night can be found.
+        const nextUnitIds = ctx.store.localFiles.consolidation.failedUnitOf(phaseError);
         if (nextUnitIds)
             sleepAuditMetadata.nextUnitIds = nextUnitIds;
-        sqliteSyncStore(ctx.hippoRoot).appendAuditEvents([{
+        await ctx.store.appendAuditEvents([{
                 tenantId: '__host__',
                 actor: ctx.actor.subject,
                 op: 'consolidate',
@@ -249,7 +258,7 @@ function emitSleepAudit(ctx, opts, dryRun, counts, phaseError) {
     }
     catch (auditErr) {
         // Logged, never thrown: a second failure must not mask the original phaseError.
-        reportAuditWriteFailure('consolidate', String(auditErr));
+        ctx.store.localFiles.consolidation.reportAuditFailure('consolidate', String(auditErr));
     }
 }
 //# sourceMappingURL=sleep-run.js.map

package/dist/api/{sleep.d.ts → sleep/sleep.d.ts}

@@ -1,8 +1,10 @@
-import type { AmbientState } from '../core/ambient.js';
-import type { Context } from './types.js';
-/** Options for `sleep`, one consolidation cycle on a SQLite store that returns counts; unlike `hippo sleep` it skips the auto-learn step. */
+import type { AmbientState } from '../../core/ambient.js';
+import { type ContextWith } from '../types.js';
+/** Options for `sleep`, one consolidation cycle on a SQLite store that returns counts; unlike `hippo sleep` it skips
+ * the auto-learn step. */
 export interface SleepOpts {
-    /** Report what a sleep would change without applying it; sharing, the ambient summary and the graph refresh are skipped. */
+    /** Report what a sleep would change without applying it; sharing,
+     * the ambient summary and the graph refresh are skipped. */
     dryRun?: boolean;
     /** Skip copying high-scoring memories to the global store under `HIPPO_HOME`. Default
      * false, so every tenant's memories are eligible; multi-tenant callers pass `true`. */
@@ -11,10 +13,11 @@ export interface SleepOpts {
 export interface SleepResult {
     active: number;
     removed: number;
-    /** Faded memories the decay pass moved to the dormant store instead of deleting (config `dormant.enabled`); absent when 0. Per-invocation counter, like
-     * `removed`. */
+    /** Faded memories the decay pass moved to the dormant store instead of deleting (config `dormant.enabled`); absent
+     * when 0. Per-invocation counter, like `removed`. */
     dormant?: number;
-    /** Dormant memories deleted for good this sleep for outliving `dormant.retentionDays`; absent when 0. Per-invocation counter, like `removed`. */
+    /** Dormant memories deleted for good this sleep for outliving `dormant.retentionDays`; absent when 0. Per-invocation
+     * counter, like `removed`. */
     dormantExpired?: number;
     mergedEpisodic: number;
     newSemantic: number;
@@ -30,9 +33,11 @@ export interface SleepResult {
         warningCount: number;
     };
     shared?: number;
-    /** Memories the auto-share secret veto withheld: rows that passed every other gate but `detectSecret`; absent when 0 or auto-share did not run. */
+    /** Memories the auto-share secret veto withheld: rows that passed every other gate but `detectSecret`; absent when 0
+     * or auto-share did not run. */
     secretSkipped?: number;
-    /** Auto-share candidates the GLOBAL store's rejection tombstone refused (one must not abort the batch); absent when 0 or auto-share did not run. */
+    /** Auto-share candidates the GLOBAL store's rejection tombstone refused (one must not abort the batch); absent when 0
+     * or auto-share did not run. */
     rejectedSkipped?: number;
     ambient?: AmbientState | null;
     /** Graph re-extraction totals across tenants rebuilt this sleep; absent when none was dirty or under dryRun.
@@ -44,6 +49,7 @@ export interface SleepResult {
     };
     details?: string[];
 }
-/** Sleeps the WHOLE hippoRoot, every tenant, so /v1/sleep stays loopback-only; SQLite only; never auto-deletes pinned, raw, kept or object-backing rows. */
-export declare function sleep(ctx: Context, opts?: SleepOpts): Promise<SleepResult>;
+/** Sleeps the WHOLE hippoRoot, every tenant, so /v1/sleep stays loopback-only; SQLite only; never auto-deletes pinned,
+ * raw, kept or object-backing rows. */
+export declare function sleep(ctx: ContextWith<'localFiles'>, opts?: SleepOpts): Promise<SleepResult>;
 //# sourceMappingURL=sleep.d.ts.map

package/dist/api/sleep/sleep.js

@@ -0,0 +1,9 @@
+// The sleep cycle: decay, consolidation, dedupe, graph extraction and the other maintenance passes.
+import { narrowContext } from '../types.js';
+import { runSleep } from './sleep-run.js';
+/** Sleeps the WHOLE hippoRoot, every tenant, so /v1/sleep stays loopback-only; SQLite only; never auto-deletes pinned,
+ * raw, kept or object-backing rows. */
+export async function sleep(ctx, opts = {}) {
+    return runSleep(narrowContext(ctx, 'auditMaintenance', 'objects', 'localFiles'), opts);
+}
+//# sourceMappingURL=sleep.js.map

package/dist/api/status.d.ts

@@ -13,7 +13,9 @@ export interface StoreStatus {
 export declare function storeStatus(ctx: Context, now: Date, atRiskBelow: number): StoreStatus;
 /** Ids and dimension of the stored vectors. Every tenant, so the host admin only. */
 export declare function vectorSummary(ctx: Context): StoredVectorSummary;
-/** Whether the stored vectors were built by a different model than `providerId`. Every tenant, so the host admin only. */
+/**
+ * Whether the stored vectors were built by a different model than `providerId`. Every tenant, so the host admin only.
+ */
 export declare function embeddingReindexNeeded(ctx: Context, providerId: string): boolean;
 /** Every stored physics particle. Every tenant, so the host admin only. */
 export declare function storedParticles(ctx: Context): PhysicsParticle[];

package/dist/api/status.js

@@ -17,7 +17,9 @@ export function vectorSummary(ctx) {
     requireHostAdmin(ctx, 'Reading every tenant');
     return storedVectorSummary(ctx.hippoRoot);
 }
-/** Whether the stored vectors were built by a different model than `providerId`. Every tenant, so the host admin only. */
+/**
+ * Whether the stored vectors were built by a different model than `providerId`. Every tenant, so the host admin only.
+ */
 export function embeddingReindexNeeded(ctx, providerId) {
     requireHostAdmin(ctx, 'Reading every tenant');
     return embeddingModelRequiresReindex(ctx.hippoRoot, providerId);

package/dist/api/store-init.d.ts

@@ -1,4 +1,7 @@
 import { type Context } from './types.js';
-/** Create the store at `ctx.hippoRoot`, or finish setting up one that exists; a store holds every tenant, so the host admin only. */
+/**
+ * Create the store at `ctx.hippoRoot`, or finish setting up one that exists; a store holds every tenant, so the host
+ * admin only.
+ */
 export declare function initMemoryStore(ctx: Context): void;
 //# sourceMappingURL=store-init.d.ts.map

package/dist/api/store-init.js

@@ -1,7 +1,10 @@
 // Creating a store for `hippo init`: the database, its mirror folders and first-run setup.
 import { initStore } from '../store/open.js';
 import { requireHostAdmin } from './types.js';
-/** Create the store at `ctx.hippoRoot`, or finish setting up one that exists; a store holds every tenant, so the host admin only. */
+/**
+ * Create the store at `ctx.hippoRoot`, or finish setting up one that exists; a store holds every tenant, so the host
+ * admin only.
+ */
 export function initMemoryStore(ctx) {
     requireHostAdmin(ctx, 'Creating a store');
     initStore(ctx.hippoRoot);

package/dist/api/tokens.d.ts

@@ -1,19 +1,20 @@
 import type { TokenSummary, TokenSurface } from '../store/token-ledger.js';
 import type { FailureSummary } from '../store/failure-log.js';
-import type { Context } from './types.js';
-/** Records memory text handed to an agent in the token ledger. Best-effort: never throws, since a ledger failure must not fail the recall or context call. */
-export declare function recordTokens(ctx: Context, surface: TokenSurface, use: {
+import type { ContextWith, StoreContext } from './types.js';
+/** Records memory text handed to an agent in the token ledger. Best-effort: never throws, since a ledger failure must
+ * not fail the recall or context call. */
+export declare function recordTokens(ctx: StoreContext, surface: TokenSurface, use: {
     items: number;
     tokens: number;
     sessionId?: string | null;
 }): Promise<void>;
-/** Token ledger totals for the tenant over the last `days` days (default 30): tokens sent, skipped as unchanged and re-read,
- * per surface, with session counts and mean tokens per session. */
-export declare function tokenSummary(ctx: Context, opts?: {
+/** Token ledger totals for the tenant over the last `days` days (default 30): tokens sent, skipped as unchanged and
+ * re-read, per surface, with session counts and mean tokens per session. */
+export declare function tokenSummary(ctx: ContextWith<'reports'>, opts?: {
     days?: number;
-}): TokenSummary;
+}): Promise<TokenSummary>;
 /** Failed tool calls by outcome, and repeats across sessions, over the last `days` days (default 30). */
-export declare function failureSummary(ctx: Context, opts?: {
+export declare function failureSummary(ctx: ContextWith<'reports'>, opts?: {
     days?: number;
-}): FailureSummary;
+}): Promise<FailureSummary>;
 //# sourceMappingURL=tokens.d.ts.map