hippo-memory 2.0.0 → 2.1.0

package/dist/api/{recall-types.d.ts → recall/types.d.ts}

@@ -1,79 +1,91 @@
-import type { ContinuityBlock } from '../store/port.js';
-import type { MemoryEntry } from '../core/memory.js';
-import type { RerankStep, SearchResult } from '../core/search-types.js';
-import type { PlanningFallacyHint, PlanningFallacyOutput, PlanningFallacyWatching } from '../predictions/planning-fallacy.js';
-import type { AnchoringHint, RecallHistorySnapshot } from './recall-history.js';
-import type { AvailabilityHint } from './availability.js';
-import type { AppendAuditOpts } from '../store/audit.js';
-import type { HippoStore } from '../store/port.js';
-import type { CallerProject } from './prompt-hook.js';
-import type { RankRecallOpts, RankRecallResult } from './recall-pipeline.js';
-import type { RecallRecording } from './recall-finish.js';
+import type { ContinuityBlock } from '../../store/port.js';
+import type { MemoryEntry } from '../../core/memory.js';
+import type { RerankStep, SearchResult } from '../../core/search-types.js';
+import type { PlanningFallacyHint, PlanningFallacyOutput, PlanningFallacyWatching } from '../../predictions/planning-fallacy.js';
+import type { AnchoringHint, RecallHistorySnapshot } from './finish.js';
+import type { AvailabilityHint } from '../availability.js';
+import type { AppendAuditOpts } from '../../store/audit.js';
+import type { HippoStore } from '../../store/port.js';
+import type { CallerProject } from '../prompt-hook.js';
+import type { RankRecallOpts, RankRecallResult } from './pipeline.js';
+import type { RecallRecording } from './finish.js';
 export interface RecallOpts {
     query: string;
     limit?: number;
-    /** Candidates the scorer loads (default: the store's 200-row window), decoupled from `limit`; NOT a hard cap, as fresh-tail and summaries can exceed `limit`.
-     *  Must be a positive finite integer (else `RecallContractError`, `invalid_scorer_window`). Library-only: HTTP, MCP and `client.ts` do not serialize it. */
+    /** Candidates the scorer loads (default: the store's 200-row window), decoupled from `limit`; NOT a hard cap, as
+     * fresh-tail and summaries can exceed `limit`. Must be a positive finite integer (else `RecallContractError`,
+     * `invalid_scorer_window`). Library-only: HTTP, MCP and `client.ts` do not serialize it. */
     scorerWindow?: number;
     /** Candidate order. `recall` always keeps the BM25 order; `retrieve` honours this. */
     mode?: 'bm25' | 'hybrid' | 'physics';
-    /** Exact-match scope filter; when undefined or empty, default-deny drops `slack:private:*` memories so an unscoped caller cannot surface private channels. */
+    /** Exact-match scope filter; when undefined or empty, default-deny drops `slack:private:*` memories so an unscoped
+     * caller cannot surface private channels. */
     scope?: string;
-    /** DAG-aware recall (default true): entries overflowing `limit` that share a level-2 parent get that summary appended instead, capped at ceil(limit 0.3)
-     * extra rows. */
+    /** DAG-aware recall (default true): entries overflowing `limit` that share a level-2 parent get that summary appended
+     * instead, capped at ceil(limit 0.3) extra rows. */
     summarizeOverflow?: boolean;
-    /** Fresh tail (default 0 = off, capped at 200): prepend the last N kind='raw' rows (tenant + scope filtered, deduped against BM25 hits) even when the
-     * query terms miss. */
+    /** Fresh tail (default 0 = off, capped at 200): prepend the last N kind='raw' rows (tenant + scope filtered, deduped
+     * against BM25 hits) even when the query terms miss. */
     freshTailCount?: number;
-    /** Restricts the fresh-tail window to one session; without it the tail is tenant-wide and surfaces newest rows across ALL sessions. */
+    /** Restricts the fresh-tail window to one session; without it the
+     * tail is tenant-wide and surfaces newest rows across ALL sessions. */
     freshTailSessionId?: string;
-    /** Include a continuity block (active task snapshot, latest matching handoff, recent session events); default false to keep the hot path cheap.
-     *  With no active snapshot, sessionHandoff is null and recentSessionEvents is [], so a stale handoff is not resurrected (use `hippo session resume`). */
+    /** Include a continuity block (active task snapshot, latest matching handoff, recent session events); default false
+     * to keep the hot path cheap. With no active snapshot, sessionHandoff is null and recentSessionEvents is [], so a
+     * stale handoff is not resurrected (use `hippo session resume`). */
     includeContinuity?: boolean;
     project?: CallerProject;
-    /** With an active goal stack for `(ctx.tenantId, sessionId)` and `goalTag` unset, `api.recall` applies the goal-stack boost; undefined means no boost.
-     *  Lives on RecallOpts, not Context, because Context is shared by remember/recall/assemble/outcome and the boost is recall-only. */
+    /** With an active goal stack for `(ctx.tenantId, sessionId)` and `goalTag` unset, `api.recall` applies the goal-stack
+     * boost; undefined means no boost. Lives on RecallOpts, not Context, because Context is shared by
+     * remember/recall/assemble/outcome and the boost is recall-only. */
     sessionId?: string;
-    /** Explicit goal-tag override: when set, the goal-stack boost is SUPPRESSED (mirrors the CLI's `goalTag === ''` gate), pinning ranking to one goal. */
+    /** Explicit goal-tag override: when set, the goal-stack boost is SUPPRESSED (mirrors the CLI's `goalTag === ''`
+     * gate), pinning ranking to one goal. */
     goalTag?: string;
-    /** Caller-supplied snapshot of the per-(tenant, session) recall ring; when present, api.recall computes `anchoringHint` from it, else no anchoring runs here.
-     *  Pure read: api.recall never mutates it; the caller appends to its own ring afterwards, passing the hint's memoryId as `anchoredOn` for the cooldown. */
+    /** Caller-supplied snapshot of the per-(tenant, session) recall ring; when present, api.recall computes
+     * `anchoringHint` from it, else no anchoring runs here. Pure read: api.recall never mutates it; the caller appends to
+     * its own ring afterwards, passing the hint's memoryId as `anchoredOn` for the cooldown. */
     recallHistory?: RecallHistorySnapshot;
-    /** Skip computing and emitting availabilityHint, for callers that run their OWN availability detection over a different result set (e.g. the MCP handler),
-     *  to avoid a double audit emission and a hint about a set the caller never surfaces. HTTP and direct SDK callers leave it unset. */
+    /** Skip computing and emitting availabilityHint, for callers that run their OWN availability detection over a
+     * different result set (e.g. the MCP handler), to avoid a double audit emission and a hint about a set the caller
+     * never surfaces. HTTP and direct SDK callers leave it unset. */
     suppressAvailabilityHint?: boolean;
-    /** Capture the lifecycle re-ranking trace (api applies only goal-boost) as `rerankTrace` plus `rerankPipeline:'api'` on each item; both fields are absent
-     * when unset. The richer CLI stages are not traced here. */
+    /** Capture the lifecycle re-ranking trace (api applies only goal-boost) as `rerankTrace` plus `rerankPipeline:'api'`
+     * on each item; both fields are absent when unset. The richer CLI stages are not traced here. */
     explain?: boolean;
-    /** Skip the recall_traces row, for callers that trace their OWN different result set, so the training corpus gets no trace mislabeled 'api'.
+    /** Skip the recall_traces row, for callers that trace their OWN different result set, so the training corpus gets no
+     *  trace mislabeled 'api'.
      *  Under `showRanked` it also drops the 'mcp' trace of the shown list. HTTP and direct SDK callers leave it unset. */
     suppressRecallTrace?: boolean;
-    /** Set only by the MCP recall tool, which ranks with its own scorer and drops copies from its own final list: this call
-     *  then keeps a memory that a merged row in the same result holds word for word. Other callers leave it unset. */
+    /** Set only by the MCP recall tool, which ranks with its own scorer and drops copies from its own final list: this
+     * call then keeps a memory that a merged row in the same result holds word for word. Other callers leave it unset. */
     keepHeldCopies?: boolean;
     leadingAudit?: readonly AppendAuditOpts[];
     recordAs?: RecallRecording;
     /** MCP recall only: `retrieve` ranks the whole scoped store and strengthens and traces
      * (pipeline 'mcp') just the ids this returns; `results` stays the window band. */
     showRanked?: (ranking: StoreRanking, result: RecallResult) => ShownRanking;
-    /** Named ranker: `retrieve` ranks with the CLI ranking core. Unset, it ranks the SQL BM25 band, or the wide hybrid list under `showRanked`. */
+    /** Named ranker: `retrieve` ranks with the CLI ranking core. Unset, it ranks the SQL BM25 band, or the wide hybrid
+     * list under `showRanked`. */
     cliCore?: CliCoreRanker;
 }
 interface CliCoreRanking {
     rank: Omit<RankRecallOpts, 'query' | 'sessionId' | 'goalTag'>;
-    /** A second store searched beside `ctx.hippoRoot`; its recall rows go to `globalStore`, else hippo.db under `globalRoot`. */
+    /** A second store searched beside `ctx.hippoRoot`: ranking reads
+     * hippo.db under `globalRoot`, and its recall rows go to `globalStore`. */
     sources?: {
-        globalRoot?: string;
-        globalStore?: HippoStore;
+        readonly globalRoot: string;
+        readonly globalStore: HippoStore;
     };
     /** Receives each operator note when ranking reaches it. */
     note?: (line: string) => void;
 }
-/** A recall the caller prints. `show` runs once ranking ends, unless it halted; `retrieve` then records the list it returns. */
+/** A recall the caller prints. `show` runs once ranking ends,
+ * unless it halted; `retrieve` then records the list it returns. */
 export interface CliCoreRecall extends CliCoreRanking {
     /** The host agent's session: it stamps the token ledger row, and the trace when the recall names no session. */
     hostSessionId?: string;
-    show: (ranking: RankRecallResult, planning: PlanningFallacyOutput) => ShownCliCore;
+    show: (ranking: RankRecallResult, planning: PlanningFallacyOutput) => ShownCliCore | Promise<ShownCliCore>;
 }
 /** A read-only look at the ranking (`hippo explain`): no hint is evaluated and nothing is written. */
 export interface CliCoreInspection extends CliCoreRanking {
@@ -90,18 +102,20 @@ export interface ShownCliCore {
     tokens: number;
     anchoredOn?: string;
 }
-/** `ids`: what the caller showed; `audit`: its own rows, written after the recall's and in the same transaction, so all land or none. */
+/** `ids`: what the caller showed; `audit`: its own rows, written after the recall's and in the same transaction, so all
+ * land or none. */
 export interface ShownRanking {
     ids: readonly string[];
     audit: readonly AppendAuditOpts[];
 }
-/** `ranked`: every scored row, best first, goal boost applied, entries as loaded; `pool`: the store after the scope filter. */
+/** `ranked`: every scored row, best first, goal boost applied,
+ * entries as loaded; `pool`: the store after the scope filter. */
 export interface StoreRanking {
     ranked: SearchResult[];
     pool: MemoryEntry[];
     droppedByScope: number;
 }
-export type { ContinuityBlock } from '../store/port.js';
+export type { ContinuityBlock } from '../../store/port.js';
 export interface RecallResultItem {
     id: string;
     content: string;
@@ -114,12 +128,14 @@ export interface RecallResultItem {
     substitutedFor?: string[];
     /** Cached descendant count from schema v25; non-zero for level-2+ rows. */
     descendantCount?: number;
-    /** True for rows from the most-recent-N kind='raw' window rather than the BM25 match; render them in a separate "recent" band. */
+    /** True for rows from the most-recent-N kind='raw' window rather
+     * than the BM25 match; render them in a separate "recent" band. */
     isFreshTail?: boolean;
-    /** Ordered lifecycle re-ranking steps that mutated this row's `score` after candidate generation (on the api pipeline, only goal-boost).
-     *  Populated ONLY when `RecallOpts.explain` is set; absent otherwise. */
+    /** Ordered lifecycle re-ranking steps that mutated this row's `score` after candidate generation (on the api
+     * pipeline, only goal-boost). Populated ONLY when `RecallOpts.explain` is set; absent otherwise. */
     rerankTrace?: RerankStep[];
-    /** Pipeline that produced `rerankTrace`: 'api' when api.recall set `explain`; the CLI carries its trace on `SearchResult` and leaves this absent. */
+    /** Pipeline that produced `rerankTrace`: 'api' when api.recall set `explain`; the CLI carries its trace on
+     * `SearchResult` and leaves this absent. */
     rerankPipeline?: 'cli' | 'api';
 }
 export interface RecallResult {
@@ -127,48 +143,57 @@ export interface RecallResult {
     total: number;
     tokens: number;
     continuity?: ContinuityBlock;
-    /** Tokens consumed by the continuity block (snapshot, handoff and the last 5 events' full content), each via Math.ceil(len/4) like `tokens`; undefined
+    /** Tokens consumed by the continuity block (snapshot, handoff and the last 5 events' full content), each via
+     *  Math.ceil(len/4) like `tokens`; undefined
      * when not requested. Callers needing a tighter budget should truncate event.content themselves. */
     continuityTokens?: number;
-    /** Scorer window used for this recall: `opts.scorerWindow`, else the store default (200). Optional in the type so test fakes built before the field still
-     * compile; always present on values returned by `api.recall`. */
+    /** Scorer window used for this recall: `opts.scorerWindow`, else the store default (200). Optional in the type so
+     * test fakes built before the field still compile; always present on values returned by `api.recall`. */
     windowSize?: number;
-    /** WYSIATI cutoff transparency: what was excluded from `results[]` and why, always populated by `api.recall`, `cmdRecall` and the MCP `hippo_recall` handler.
-     *  Counters are per-pipeline reports of that pipeline's own filter sites, not normalised across pipelines. Optional for test fakes. */
+    /** WYSIATI cutoff transparency: what was excluded from `results[]` and why, always populated by `api.recall`,
+     * `cmdRecall` and the MCP `hippo_recall` handler. Counters are per-pipeline reports of that pipeline's own filter
+     * sites, not normalised across pipelines. Optional for test fakes. */
     suppressionSummary?: RecallSuppressionSummary;
-    /** Planning-fallacy hint: base-rate stats when the query carries a forward-prediction phrase and the closest prediction class has closed data.
-     *  Pipeline-invariant (depends only on queryText, tenantId, predictions state), so MCP and CLI read it from here. Disabled by `HIPPO_AUTODEBIAS=off`. */
+    /** Planning-fallacy hint: base-rate stats when the query carries a forward-prediction phrase and the closest
+     * prediction class has closed data. Pipeline-invariant (depends only on queryText, tenantId, predictions state), so
+     * MCP and CLI read it from here. Disabled by `HIPPO_AUTODEBIAS=off`. */
     planningFallacyHint?: PlanningFallacyHint;
-    /** "Watching" variant emitted when the forward-claim regex matched but no baserate could be produced (no class overlap, or a tie at the best score).
+    /** "Watching" variant emitted when the forward-claim regex matched but no baserate could be produced (no class
+     *  overlap, or a tie at the best score).
      *  Mutually exclusive with `planningFallacyHint`; pipeline-invariant. Disabled by `HIPPO_AUTODEBIAS=off`. */
     planningFallacyWatching?: PlanningFallacyWatching;
-    /** Anchoring hint from api.recall's own compute against `opts.recallHistory` (query_repeat or memory_dominance); each pipeline computes its OWN hint.
-     *  Null on CLI-routed calls, since cmdRecall does not thread its ring through `opts.recallHistory`. Disabled by `HIPPO_ANCHORING=off`. */
+    /** Anchoring hint from api.recall's own compute against `opts.recallHistory` (query_repeat or memory_dominance); each
+     * pipeline computes its OWN hint. Null on CLI-routed calls, since cmdRecall does not thread its ring through
+     * `opts.recallHistory`. Disabled by `HIPPO_ANCHORING=off`. */
     anchoringHint?: AnchoringHint;
-    /** Availability/recency-bias hint: per-pipeline, soft warning only (never filters or reorders); fires when the returned slice is recency-dominated
+    /** Availability/recency-bias hint: per-pipeline, soft warning only (never filters or reorders); fires when the
+     *  returned slice is recency-dominated
      *  while older relevant matches in the pool were passed over. Disabled by `HIPPO_AVAILABILITY=off`. */
     availabilityHint?: AvailabilityHint;
 }
-/** WYSIATI cutoff transparency: what the pipeline excluded from `results[]`, so the agent does not treat the cutoff as the full picture.
- *  Counters are honest per-path reports of the pipeline that produced this RecallResult, not normalised across pipelines. */
+/** WYSIATI cutoff transparency: what the pipeline excluded from `results[]`, so the agent does not treat the cutoff as
+ * the full picture. Counters are honest per-path reports of the pipeline that produced this RecallResult, not
+ * normalised across pipelines. */
 export interface RecallSuppressionSummary {
     /** Candidates loaded from the store before any post-load filter or limit cut;
      *  each pipeline counts at its own load (api.recall: after `loadRecallSearchEntries`). */
     totalCandidates: number;
-    /** Candidates dropped by any non-budget filter site, pre- or post-rank; the final limit slice is counted in droppedByBudget instead.
-     *  Each pipeline counts its own filters (cmdRecall: --as-of, superseded, --filter-conflicts, --outcome, --layer; MCP: scope filter before search). */
+    /** Candidates dropped by any non-budget filter site, pre- or post-rank; the final limit slice is counted in
+     * droppedByBudget instead. Each pipeline counts its own filters (cmdRecall: --as-of, superseded, --filter-conflicts,
+     * --outcome, --layer; MCP: scope filter before search). */
     droppedPreRank: number;
-    /** Candidates loaded but cut by the final `limit` slice after scoring (api.recall: `entries.length - baseSlice.length`; other pipelines count pre- minus
-     * post-slice). */
+    /** Candidates loaded but cut by the final `limit` slice after scoring (api.recall: `entries.length -
+     * baseSlice.length`; other pipelines count pre- minus post-slice). */
     droppedByBudget: number;
-    /** DAG-L2 summaries substituted back in to mitigate overflow (api.recall: after the `summarizeOverflow` block; cmdRecall: 0; MCP: rows from
-     * apiResult.tailOrSummary). */
+    /** DAG-L2 summaries substituted back in to mitigate overflow (api.recall: after the `summarizeOverflow` block;
+     * cmdRecall: 0; MCP: rows from apiResult.tailOrSummary). */
     summarySubstitutionsAdded: number;
-    /** Fresh-tail `kind='raw'` rows prepended (api.recall: `freshRanked.length` when `freshTailCount > 0`; cmdRecall: 0; MCP: rows from
-     * apiResult.tailOrSummary). */
+    /** Fresh-tail `kind='raw'` rows prepended (api.recall: `freshRanked.length` when `freshTailCount > 0`; cmdRecall: 0;
+     * MCP: rows from apiResult.tailOrSummary). */
     freshTailAdded: number;
-    /** Memories suppressed by interference: incremented by 1 PER PIPELINE when its own memory_dominance verdict fires (see `detectAnchoring()` in
-     * src/api/recall-history.ts). Each pipeline bumps its OWN summary from its own detector and ring buffer, so this is not a cross-pipeline aggregate. */
+    /** Memories suppressed by interference: incremented by 1 PER PIPELINE when its own memory_dominance verdict fires
+     * (see `detectAnchoring()` in src/api/recall/finish.ts). Each pipeline bumps its OWN summary from its own detector
+     * and ring buffer, so this is not a cross-pipeline aggregate. */
     suppressedByInterference: number;
 }
-//# sourceMappingURL=recall-types.d.ts.map
+//# sourceMappingURL=types.d.ts.map

package/dist/api/{recall-types.js → recall/types.js}

@@ -1,3 +1,3 @@
 // Option and result shapes for recall and retrieve.
 export {};
-//# sourceMappingURL=recall-types.js.map
+//# sourceMappingURL=types.js.map

package/dist/api/session-end.d.ts

@@ -1,10 +1,11 @@
 import type { HandoffEvidence } from '../core/handoff.js';
 import type { TaskSnapshot } from '../store/rows.js';
-import type { Context } from './types.js';
+import type { Context, ContextWith } from './types.js';
 /** What closing one ended session needs from the host; the two readers run only when the handoff is written. */
 export interface SessionClose {
     sessionId: string | null;
-    /** A reply's end, not the session's: the handoff is updated in place and the snapshot stays for the next compaction. */
+    /** A reply's end, not the session's: the handoff is updated in place and the snapshot stays for the next
+     * compaction. */
     turn: boolean;
     /** The transcript's working state, or null with no readable transcript. */
     workingState: () => Pick<TaskSnapshot, 'task' | 'summary' | 'next_step'> | null;
@@ -12,14 +13,17 @@ export interface SessionClose {
     /** One line to the session-end log. */
     log: (line: string) => void;
 }
-/** Writes the session's handoff, then closes its snapshot unless `turn`; each step logs its own failure and never throws.
- *  The handoff goes first, while the snapshot writeSessionEndHandoff reads is still active. */
-export declare function closeEndedSession(ctx: Context, close: SessionClose): void;
-/** Books the ending session's re-reads in each store its ledger rows can land in (`ctx.hippoRoot` and global); returns the log lines. */
+/** Writes the session's handoff, then closes its snapshot unless `turn`; each step logs its own failure and never
+ * throws. The handoff goes first, while the snapshot writeSessionEndHandoff reads is still active. */
+export declare function closeEndedSession(ctx: ContextWith<'sessions'>, close: SessionClose): Promise<void>;
+/** Books the ending session's re-reads in each store its ledger rows can land in (`ctx.hippoRoot` and global); returns
+ * the log lines. */
 export declare function bookSessionRereads(ctx: Context, transcriptPath: string | undefined, sessionId: string | null): Promise<string[]>;
-/** The block a compaction lost: the fresh task snapshot and its session trail, or null with none or another session's snapshot. */
-export declare function compactResumeBlock(ctx: Context, payloadSessionId: string | null): string | null;
-/** What one session-end run needs from its host; the host owns sleep, transcript reading and capture, this module owns the order. */
+/** The block a compaction lost: the fresh task snapshot and its session trail, or null with none or another session's
+ * snapshot. */
+export declare function compactResumeBlock(ctx: ContextWith<'sessions'>, payloadSessionId: string | null): Promise<string | null>;
+/** What one session-end run needs from its host; the host owns sleep, transcript reading and capture, this module owns
+ * the order. */
 export interface SessionEndWork<Scan> {
     mode: 'turn' | 'full';
     hippoRoot: string;
@@ -27,9 +31,9 @@ export interface SessionEndWork<Scan> {
     sessionId: string | null;
     transcriptPath: string | undefined;
     /** Builds the call context for one store root. */
-    contextFor: (root: string) => Context;
-    /** The store the run captures into: the project store, else global. */
-    storeRoot: () => string;
+    contextFor: (root: string) => ContextWith<'sessions'>;
+    /** The store the run captures into: the project store, else global; null when neither exists. */
+    storeRoot: () => string | null;
     /** One line to the session-end log; `startFresh` restarts the file. */
     log: (line: string, opts?: {
         startFresh?: boolean;

package/dist/api/session-end.js

@@ -1,35 +1,38 @@
 // The store writes a session's end makes after sleep and capture (handoff, snapshot close, re-read count), and the
 // compact-resume read; the hook verbs keep stdin, spawning and the log file.
 import * as path from 'path';
-import { isInitialized } from '../core/project-identity.js';
-import { closeTaskSnapshotsForSession, listSessionEvents, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot } from '../store/sessions.js';
-import { writeSessionEndHandoff } from '../store/handoffs.js';
 import { readApiCalls, recordRereads } from '../store/token-ledger.js';
-import { getGlobalRoot } from '../sharing/global-store.js';
 import { truncateCodePointSafe } from '../util/transcript-tail.js';
-import { errorMessage, log } from '../util/log.js';
+import { errorMessage, log, errorFields } from '../util/log.js';
 import { COMPACT_RESUME_EVENT_CONTENT_CAP, COMPACT_RESUME_MAX_AGE_MS, compactResumeText } from './context-render.js';
-/** Writes the session's handoff, then closes its snapshot unless `turn`; each step logs its own failure and never throws.
- *  The handoff goes first, while the snapshot writeSessionEndHandoff reads is still active. */
-export function closeEndedSession(ctx, close) {
+/** Writes the session's handoff, then closes its snapshot unless `turn`; each step logs its own failure and never
+ * throws. The handoff goes first, while the snapshot writeSessionEndHandoff reads is still active. */
+export async function closeEndedSession(ctx, close) {
     if (close.sessionId)
-        writeEndHandoff(ctx, close.sessionId, close);
+        await writeEndHandoff(ctx, close.sessionId, close);
     if (close.turn) {
         close.log('skip snapshot close: turn mode');
         return;
     }
-    closeSnapshot(ctx, close.sessionId, close.log);
+    await closeSnapshot(ctx, close.sessionId, close.log);
 }
-function writeEndHandoff(ctx, sessionId, close) {
+async function writeEndHandoff(ctx, sessionId, close) {
+    const { sessions } = ctx.store;
     try {
-        const ownSnapshot = loadActiveTaskSnapshot(ctx.hippoRoot, ctx.tenantId)?.session_id === sessionId;
-        // A never-compacted session has no snapshot; read even when it has one, as another session's PreCompact can take the slot before the write.
+        const ownSnapshot = (await sessions.loadSnapshot(ctx.tenantId, null))?.session_id === sessionId;
+        // A never-compacted session has no snapshot; read even when it has one, as another session's PreCompact can take
+        // the slot before the write.
         const derived = close.workingState();
         if (!ownSnapshot && !derived) {
             close.log('skip: no snapshot or transcript for session');
             return;
         }
-        const handoff = writeSessionEndHandoff(ctx.hippoRoot, { tenantId: ctx.tenantId, sessionId, evidence: close.evidence(), derived, inPlace: close.turn });
+        const handoff = await sessions.writeSessionEndHandoff(ctx.tenantId, {
+            sessionId,
+            evidence: close.evidence(),
+            derived,
+            inPlace: close.turn,
+        });
         close.log(handoff ? `wrote handoff for session ${sessionId}` : `skip: kept the existing handoff for session ${sessionId}`);
     }
     catch (err) {
@@ -37,10 +40,10 @@ function writeEndHandoff(ctx, sessionId, close) {
     }
 }
 // If session-end never fires (crash, kill -9), the freshness bound in loadFreshActiveTaskSnapshot is the backstop.
-function closeSnapshot(ctx, sessionId, line) {
+async function closeSnapshot(ctx, sessionId, line) {
     try {
         if (sessionId) {
-            const closed = closeTaskSnapshotsForSession(ctx.hippoRoot, ctx.tenantId, sessionId);
+            const closed = await ctx.store.sessions.closeSessionSnapshots(ctx.tenantId, sessionId, 'session-ended', null);
             line(`closed ${closed} active snapshot(s) for session ${sessionId}`);
         }
         else {
@@ -51,7 +54,8 @@ function closeSnapshot(ctx, sessionId, line) {
         line(`snapshot close failed: ${errorMessage(err)}`);
     }
 }
-/** Books the ending session's re-reads in each store its ledger rows can land in (`ctx.hippoRoot` and global); returns the log lines. */
+/** Books the ending session's re-reads in each store its ledger rows can land in (`ctx.hippoRoot` and global); returns
+ * the log lines. */
 export async function bookSessionRereads(ctx, transcriptPath, sessionId) {
     if (!transcriptPath || !sessionId)
         return [];
@@ -62,7 +66,8 @@ export async function bookSessionRereads(ctx, transcriptPath, sessionId) {
     catch (err) {
         return [`skip re-read count: cannot read the transcript: ${errorMessage(err)}`];
     }
-    const roots = new Set([ctx.hippoRoot, getGlobalRoot()].filter((root) => isInitialized(root)).map((root) => path.resolve(root)));
+    const roots = new Set([(ctx.reach?.hasLocal ?? true) ? ctx.hippoRoot : null, ctx.reach?.global?.root]
+        .flatMap((root) => (root ? [path.resolve(root)] : [])));
     const lines = [];
     let tokens = 0;
     for (const root of roots) {
@@ -77,24 +82,30 @@ export async function bookSessionRereads(ctx, transcriptPath, sessionId) {
     lines.push(`re-read ${tokens} tokens over ${read.calls.length} model calls for session ${sessionId}${skipped}`);
     return lines;
 }
-/** The block a compaction lost: the fresh task snapshot and its session trail, or null with none or another session's snapshot. */
-export function compactResumeBlock(ctx, payloadSessionId) {
-    const snapshot = loadFreshActiveTaskSnapshot(ctx.hippoRoot, ctx.tenantId, { maxAgeMs: COMPACT_RESUME_MAX_AGE_MS });
-    // Concurrent sessions must not cross-restore: only when both ids are present and differ, so a manual run with no payload id still prints.
-    if (!snapshot || (payloadSessionId !== null && snapshot.session_id !== null && payloadSessionId !== snapshot.session_id))
+/** The block a compaction lost: the fresh task snapshot and its session trail, or null with none or another session's
+ * snapshot. */
+export async function compactResumeBlock(ctx, payloadSessionId) {
+    const { sessions } = ctx.store;
+    const snapshot = await sessions.loadFreshSnapshot(ctx.tenantId, { maxAgeMs: COMPACT_RESUME_MAX_AGE_MS }, null);
+    // Concurrent sessions must not cross-restore: only when both ids are present and differ, so a manual run with no
+    // payload id still prints.
+    if (!snapshot)
         return null;
+    if (payloadSessionId !== null && snapshot.session_id !== null && payloadSessionId !== snapshot.session_id) {
+        return null;
+    }
     // A bad trail row costs the trail, not the snapshot; stderr stays out of the model's context.
     let events = [];
     try {
         if (snapshot.session_id) {
-            events = listSessionEvents(ctx.hippoRoot, ctx.tenantId, { session_id: snapshot.session_id }).map((e) => ({
+            events = (await sessions.listEvents(ctx.tenantId, { sessionId: snapshot.session_id })).map((e) => ({
                 ...e,
                 content: truncateCodePointSafe(e.content, COMPACT_RESUME_EVENT_CONTENT_CAP),
             }));
         }
     }
     catch (err) {
-        log.warn(`hippo compact-resume: trail skipped: ${errorMessage(err)}`);
+        log.warn(`hippo compact-resume: trail skipped: ${errorMessage(err)}`, errorFields(err));
     }
     return compactResumeText(snapshot, events);
 }
@@ -102,13 +113,18 @@ export function compactResumeBlock(ctx, payloadSessionId) {
 export async function sessionEndWork(w) {
     const rereadLog = await bookSessionRereads(w.contextFor(w.hippoRoot), w.transcriptPath, w.sessionId)
         .catch((err) => [`re-read count failed: ${errorMessage(err)}`]);
-    // Sleep starts the log file afresh, so the lines go in after it; on exit too, in case sleep exits the process.
-    const flushRereadLog = () => { for (const line of rereadLog.splice(0))
-        w.log(line); };
+    // Sleep starts the log file afresh, so the lines go in after it; on exit too, in case sleep exits the process. A
+    // flushed log drops its exit listener, so a long-lived host does not gain one per session; it stays only while lines
+    // wait.
+    const flushRereadLog = () => {
+        process.off('exit', flushRereadLog);
+        for (const line of rereadLog.splice(0))
+            w.log(line);
+    };
     process.once('exit', flushRereadLog);
     // A folder with neither a project nor a global store must not get one made.
     const store = w.storeRoot();
-    if (!isInitialized(store)) {
+    if (store === null) {
         w.log('skip: no hippo store for this folder or globally', { startFresh: true });
         flushRereadLog();
         return;
@@ -120,7 +136,7 @@ export async function sessionEndWork(w) {
     w.digest(scan, (line) => w.log(line));
     // Only this session's snapshot, and only after sleep and capture.
     const closeLog = (line) => w.log(line);
-    closeEndedSession(w.contextFor(store), {
+    await closeEndedSession(w.contextFor(store), {
         sessionId: w.sessionId,
         turn: w.mode === 'turn',
         workingState: () => (w.transcriptPath ? w.workingState(closeLog) : null),

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

@@ -1,6 +1,9 @@
-import type { HippoConfig } from '../core/config.js';
+import type { HippoConfig } from '../../core/config.js';
 export declare const autoSleepInFlight: Set<string>;
-/** Runs one auto-sleep consolidation of `hippoRoot`: the HTTP server passes one that runs it off its event loop, in a child process. */
+/**
+ * Runs one auto-sleep consolidation of `hippoRoot`: the HTTP server passes one that runs it off its event loop, in a
+ * child process; stdio passes one that runs it in its own.
+ */
 export type AutoSleepRunner = (hippoRoot: string) => Promise<void>;
 export interface AutoSleepDue {
     enabled: boolean;
@@ -10,7 +13,8 @@ export interface AutoSleepDue {
 }
 /** Counts only when enabled: the count opens the store. */
 export declare function autoSleepDue(hippoRoot: string, tenantId: string, config: HippoConfig['autoSleep']): AutoSleepDue;
-/** One run per store at a time; `allowed` is the caller's own gate. Consolidation is host-wide, so only the host tenant may start it.
- * Without `run`, it runs in process. */
-export declare function startAutoSleepIfDue(hippoRoot: string, tenantId: string, config: HippoConfig['autoSleep'], allowed: boolean, run?: AutoSleepRunner): void;
+/**
+ * One run per store at a time; `allowed` is the caller's own gate. Consolidation is host-wide, so only the host tenant
+ * may start it. */
+export declare function startAutoSleepIfDue(hippoRoot: string, tenantId: string, config: HippoConfig['autoSleep'], allowed: boolean, run: AutoSleepRunner): void;
 //# sourceMappingURL=auto-sleep.d.ts.map

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

@@ -1,9 +1,7 @@
 // When a write starts a background sleep; the MCP remember tool and the session-close hook share it.
-import { errorFields, errorMessage, log } from '../util/log.js';
-import { countCreatedSinceLastSleep } from '../store/index-and-stats.js';
-import { consolidate } from '../consolidate/sleep.js';
-import { outsideRequestStores, runWithRequestStores, scopedBusyWait } from '../db/index.js';
-import { resolveTenantId } from '../store/tenant.js';
+import { errorFields, errorMessage, log } from '../../util/log.js';
+import { countCreatedSinceLastSleep } from '../../store/index-and-stats.js';
+import { resolveTenantId } from '../../store/tenant.js';
 export const autoSleepInFlight = new Set();
 /** Counts only when enabled: the count opens the store. */
 export function autoSleepDue(hippoRoot, tenantId, config) {
@@ -11,8 +9,9 @@ export function autoSleepDue(hippoRoot, tenantId, config) {
     const count = enabled ? countCreatedSinceLastSleep(hippoRoot, tenantId) : 0;
     return { enabled, count, threshold, due: enabled && count >= threshold };
 }
-/** One run per store at a time; `allowed` is the caller's own gate. Consolidation is host-wide, so only the host tenant may start it.
- * Without `run`, it runs in process. */
+/**
+ * One run per store at a time; `allowed` is the caller's own gate. Consolidation is host-wide, so only the host tenant
+ * may start it. */
 export function startAutoSleepIfDue(hippoRoot, tenantId, config, allowed, run) {
     if (!allowed ||
         !config.enabled ||
@@ -22,11 +21,7 @@ export function startAutoSleepIfDue(hippoRoot, tenantId, config, allowed, run) {
         return;
     autoSleepInFlight.add(hippoRoot);
     // Fire-and-forget (never block the response); an unhandled rejection would kill the server, so log it.
-    // Its own scope: the call's closes a handle the sleep still holds across its pauses, but the caller's lock wait carries over.
-    const busyWaitMs = scopedBusyWait();
-    const started = run
-        ? run(hippoRoot)
-        : outsideRequestStores(() => runWithRequestStores(() => consolidate(hippoRoot), { busyWaitMs }));
+    const started = run(hippoRoot);
     started
         .catch((err) => {
         log.error(`auto-sleep consolidate failed (tenant ${tenantId}): ${errorMessage(err)}`, errorFields(err));

package/dist/api/sleep/dormant.d.ts

@@ -0,0 +1,25 @@
+import type { DormantMemory, ListDormantOpts } from '../../store/dormant.js';
+import { type MemoryEntry } from '../../core/memory.js';
+import type { ContextWith } from '../types.js';
+type DormantContext = ContextWith<'dormant'>;
+/**
+ * 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 declare function listDormant(ctx: DormantContext, opts?: ListDormantOpts): Promise<DormantMemory[]>;
+/**
+ * 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 declare function restoreDormant(ctx: DormantContext, id: string): Promise<MemoryEntry>;
+/**
+ * Permanently deletes a dormant memory, the explicit "forget it for good"; throws when the tenant has no dormant memory
+ * with that id.
+ */
+export declare function forgetDormant(ctx: DormantContext, id: string): Promise<void>;
+/** Whether the tenant holds a dormant memory with this id that the caller may touch (for "not found" hints). */
+export declare function isDormant(ctx: DormantContext, id: string): Promise<boolean>;
+export {};
+//# sourceMappingURL=dormant.d.ts.map