hippo-memory 1.11.2 → 1.11.3

package/dist/dedupe.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Store-level deduplication. Scans for near-duplicate memories by content
+ * Jaccard overlap, keeps the stronger copy (by strength + retrieval count),
+ * removes the rest.
+ *
+ * Extracted from cli.ts in Episode A (v1.11.3) so `api.sleep` can dedupe
+ * during the consolidation pipeline without violating the cli -> api
+ * dependency direction. `cmdDedup` in cli.ts continues to import and use
+ * this function unchanged.
+ */
+export interface DedupPair {
+    kept: string;
+    keptContent: string;
+    keptLayer: string;
+    keptStrength: number;
+    removed: string;
+    removedContent: string;
+    removedLayer: string;
+    removedStrength: number;
+    similarity: number;
+}
+/**
+ * Scan the store for near-duplicate memories and remove the weaker copy.
+ * Two memories are duplicates if their content has > threshold Jaccard overlap.
+ * Keeps the one with higher strength (or more retrievals if tied).
+ */
+export declare function deduplicateStore(hippoRoot: string, options?: {
+    threshold?: number;
+    dryRun?: boolean;
+}): {
+    removed: number;
+    pairs: DedupPair[];
+};
+//# sourceMappingURL=dedupe.d.ts.map

package/dist/dedupe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedupe.d.ts","sourceRoot":"","sources":["../src/dedupe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACrD;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,EAAE,CAAA;CAAE,CA6CzC"}

package/dist/dedupe.js

@@ -0,0 +1,61 @@
+/**
+ * Store-level deduplication. Scans for near-duplicate memories by content
+ * Jaccard overlap, keeps the stronger copy (by strength + retrieval count),
+ * removes the rest.
+ *
+ * Extracted from cli.ts in Episode A (v1.11.3) so `api.sleep` can dedupe
+ * during the consolidation pipeline without violating the cli -> api
+ * dependency direction. `cmdDedup` in cli.ts continues to import and use
+ * this function unchanged.
+ */
+import { textOverlap } from './search.js';
+import { loadAllEntries, deleteEntry } from './store.js';
+/**
+ * Scan the store for near-duplicate memories and remove the weaker copy.
+ * Two memories are duplicates if their content has > threshold Jaccard overlap.
+ * Keeps the one with higher strength (or more retrievals if tied).
+ */
+export function deduplicateStore(hippoRoot, options = {}) {
+    const threshold = options.threshold ?? 0.7;
+    const dryRun = options.dryRun ?? false;
+    const entries = loadAllEntries(hippoRoot);
+    // Sort by strength desc, then retrieval count, so we keep the most valuable copy
+    entries.sort((a, b) => {
+        const sDiff = (b.strength ?? 0) - (a.strength ?? 0);
+        if (Math.abs(sDiff) > 0.01)
+            return sDiff;
+        return (b.retrieval_count ?? 0) - (a.retrieval_count ?? 0);
+    });
+    const removed = new Set();
+    const pairs = [];
+    for (let i = 0; i < entries.length; i++) {
+        if (removed.has(entries[i].id))
+            continue;
+        for (let j = i + 1; j < entries.length; j++) {
+            if (removed.has(entries[j].id))
+                continue;
+            const similarity = textOverlap(entries[i].content, entries[j].content);
+            if (similarity <= threshold)
+                continue;
+            removed.add(entries[j].id);
+            pairs.push({
+                kept: entries[i].id,
+                keptContent: entries[i].content,
+                keptLayer: entries[i].layer,
+                keptStrength: entries[i].strength ?? 0,
+                removed: entries[j].id,
+                removedContent: entries[j].content,
+                removedLayer: entries[j].layer,
+                removedStrength: entries[j].strength ?? 0,
+                similarity,
+            });
+        }
+    }
+    if (!dryRun) {
+        for (const id of removed) {
+            deleteEntry(hippoRoot, id);
+        }
+    }
+    return { removed: removed.size, pairs };
+}
+//# sourceMappingURL=dedupe.js.map

package/dist/dedupe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedupe.js","sourceRoot":"","sources":["../src/dedupe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAczD;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,SAAiB,EACjB,UAAoD,EAAE;IAEtD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,GAAG,CAAC;IAC3C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC;IACvC,MAAM,OAAO,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;IAE1C,iFAAiF;IACjF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACpB,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC;QACpD,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI;YAAE,OAAO,KAAK,CAAC;QACzC,OAAO,CAAC,CAAC,CAAC,eAAe,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,eAAe,IAAI,CAAC,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,MAAM,KAAK,GAAgB,EAAE,CAAC;IAE9B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACxC,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAAE,SAAS;QACzC,KAAK,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5C,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBAAE,SAAS;YAEzC,MAAM,UAAU,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;YACvE,IAAI,UAAU,IAAI,SAAS;gBAAE,SAAS;YAEtC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAC3B,KAAK,CAAC,IAAI,CAAC;gBACT,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE;gBACnB,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO;gBAC/B,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK;gBAC3B,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC;gBACtC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE;gBACtB,cAAc,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO;gBAClC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK;gBAC9B,eAAe,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC;gBACzC,UAAU;aACX,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,KAAK,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;YACzB,WAAW,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;AAC1C,CAAC"}

package/dist/src/api.js

@@ -8,13 +8,19 @@
  */
 import { createHash } from 'node:crypto';
 import { openHippoDb, closeHippoDb } from './db.js';
-import { writeEntry, writeEntryDbOnly, writeEntryMirrors, readEntry, deleteEntry, loadRecallSearchEntries, loadEntriesByIds, loadChildrenOf, loadFreshRawMemories, loadSessionRawMemories, countSessionRawMemories, DEFAULT_SEARCH_CANDIDATE_LIMIT, RECALL_DEFAULT_DENY_SCOPES, removeEntryMirrors, loadActiveTaskSnapshot, loadLatestHandoff, listSessionEvents, } from './store.js';
-import { createMemory, applyOutcome, Layer, } from './memory.js';
-import { appendAuditEvent, queryAuditEvents, } from './audit.js';
-import { promoteToGlobal, getGlobalRoot } from './shared.js';
+import { writeEntry, writeEntryDbOnly, writeEntryMirrors, readEntry, deleteEntry, loadRecallSearchEntries, loadEntriesByIds, loadChildrenOf, loadFreshRawMemories, loadSessionRawMemories, countSessionRawMemories, DEFAULT_SEARCH_CANDIDATE_LIMIT, RECALL_DEFAULT_DENY_SCOPES, removeEntryMirrors, loadActiveTaskSnapshot, loadLatestHandoff, listSessionEvents, loadIndex, saveIndex, loadAllEntries, updateStats, isInitialized, } from './store.js';
+import { createMemory, applyOutcome, calculateStrength, Layer, } from './memory.js';
+import { appendAuditEvent, queryAuditEvents, auditMemories, } from './audit.js';
+import { promoteToGlobal, getGlobalRoot, autoShare, searchBothHybrid } from './shared.js';
 import { archiveRawMemory } from './raw-archive.js';
 import { createApiKey, listApiKeys, revokeApiKey, } from './auth.js';
 import { applyGoalStackBoost } from './goals.js';
+import { markRetrieved, estimateTokens, hybridSearch, physicsSearch } from './search.js';
+import { scopeMatch } from './scope.js';
+import { consolidate } from './consolidate.js';
+import { loadConfig } from './config.js';
+import { deduplicateStore } from './dedupe.js';
+import { computeAmbientState } from './ambient.js';
 /**
  * Thrown by `api.recall` when a caller's options violate a recall contract
  * that has been opted into via env. Carries a stable `code` field for HTTP /
@@ -998,4 +1004,390 @@ export function auditList(ctx, opts) {
         closeHippoDb(db);
     }
 }
+/**
+ * Assemble a context bundle: recalled memories (pinned-only / strength-sorted
+ * fallback / hybrid search) + active task snapshot + session handoff + recent
+ * session events. Budget-bounded, tenant-scoped. Mutates `last_retrieval_ids`
+ * + emits a 'recall' audit row for non-pinned, non-'*' queries.
+ *
+ * Behaves like the pre-extraction `cmdContext` data-loading + selection
+ * pipeline. CLI presentation (markdown / json / additional-context rendering)
+ * stays in `cli.ts`.
+ *
+ * Tenant scope: all `loadAllEntries` / snapshot / handoff / events reads use
+ * `ctx.tenantId`. Cross-tenant rows are filtered out.
+ *
+ * Returns an empty result (`entries: []`, snapshot/handoff/events undefined)
+ * when there's nothing to surface (no memories AND no snapshot AND no handoff
+ * AND no recent events).
+ */
+export async function getContext(ctx, opts = {}) {
+    const pinnedOnly = opts.pinnedOnly === true;
+    const budget = opts.budget ?? 1500;
+    const limit = opts.limit ?? Number.POSITIVE_INFINITY;
+    const includeRecent = opts.includeRecent ?? 0;
+    const activeScope = opts.scope ?? '';
+    if (budget <= 0) {
+        return { entries: [], tokens: 0 };
+    }
+    // Pinned-only path is allowed against an un-initialised local store (the
+    // UserPromptSubmit hook can run in directories without a .hippo). Non-pinned
+    // path requires an initialised local store; callers should check first.
+    const hasLocal = isInitialized(ctx.hippoRoot);
+    const query = (opts.q ?? '').trim() || '*';
+    const globalRoot = getGlobalRoot();
+    const hasGlobal = isInitialized(globalRoot);
+    // Tenant-scoped loads (v1.11.1 lesson: NEVER resolveTenantId({}) here).
+    let localEntries = hasLocal ? loadAllEntries(ctx.hippoRoot, ctx.tenantId) : [];
+    let globalEntries = hasGlobal ? loadAllEntries(globalRoot, ctx.tenantId) : [];
+    // Filter superseded — context never includes superseded rows.
+    localEntries = localEntries.filter((e) => !e.superseded_by);
+    globalEntries = globalEntries.filter((e) => !e.superseded_by);
+    const activeSnapshot = hasLocal
+        ? loadActiveTaskSnapshot(ctx.hippoRoot, ctx.tenantId)
+        : null;
+    const sessionHandoff = hasLocal && activeSnapshot?.session_id
+        ? loadLatestHandoff(ctx.hippoRoot, ctx.tenantId, activeSnapshot.session_id)
+        : null;
+    const recentSessionEvents = hasLocal && activeSnapshot?.session_id
+        ? listSessionEvents(ctx.hippoRoot, ctx.tenantId, {
+            session_id: activeSnapshot.session_id,
+            limit: 5,
+        })
+        : [];
+    if (localEntries.length === 0 &&
+        globalEntries.length === 0 &&
+        !activeSnapshot &&
+        !sessionHandoff &&
+        recentSessionEvents.length === 0) {
+        return { entries: [], tokens: 0 };
+    }
+    let selectedItems = [];
+    let totalTokens = 0;
+    if (pinnedOnly) {
+        // loadConfig is safe even when local isn't initialised — returns defaults.
+        const pinnedCfg = loadConfig(ctx.hippoRoot);
+        if (!pinnedCfg.pinnedInject.enabled) {
+            return { entries: [], tokens: 0 };
+        }
+        // Effective budget: explicit opts.budget wins over config.
+        const effBudget = opts.budget !== undefined ? budget : pinnedCfg.pinnedInject.budget;
+        const nowP = new Date();
+        const selectedIds = new Set();
+        let usedP = 0;
+        if (includeRecent > 0) {
+            const recent = [
+                ...localEntries.map((entry) => ({ entry, isGlobal: false })),
+                ...globalEntries.map((entry) => ({ entry, isGlobal: true })),
+            ]
+                .sort((a, b) => {
+                const byCreated = Date.parse(b.entry.created) - Date.parse(a.entry.created);
+                return byCreated !== 0 ? byCreated : b.entry.id.localeCompare(a.entry.id);
+            })
+                .slice(0, includeRecent)
+                .map(({ entry, isGlobal }) => ({
+                entry,
+                score: calculateStrength(entry, nowP) * (isGlobal ? 1 / 1.2 : 1),
+                tokens: estimateTokens(entry.content),
+                isGlobal,
+            }));
+            for (const r of recent) {
+                if (selectedIds.has(r.entry.id))
+                    continue;
+                if (usedP + r.tokens > effBudget)
+                    continue;
+                selectedItems.push(r);
+                selectedIds.add(r.entry.id);
+                usedP += r.tokens;
+            }
+        }
+        const pinnedLocal = localEntries.filter((e) => e.pinned);
+        const pinnedGlobal = globalEntries.filter((e) => e.pinned);
+        if (pinnedLocal.length === 0 &&
+            pinnedGlobal.length === 0 &&
+            selectedItems.length === 0) {
+            return { entries: [], tokens: 0 };
+        }
+        const rankedPinned = [
+            ...pinnedLocal.map((e) => ({ entry: e, isGlobal: false })),
+            ...pinnedGlobal.map((e) => ({ entry: e, isGlobal: true })),
+        ]
+            .map(({ entry, isGlobal }) => {
+            const scopeSig = scopeMatch(entry.tags, activeScope);
+            const sBst = scopeSig === 1 ? 1.5 : scopeSig === -1 ? 0.5 : 1.0;
+            return {
+                entry,
+                score: calculateStrength(entry, nowP) * (isGlobal ? 1 / 1.2 : 1) * sBst,
+                tokens: estimateTokens(entry.content),
+                isGlobal,
+            };
+        })
+            .sort((a, b) => b.score - a.score);
+        for (const r of rankedPinned) {
+            if (selectedIds.has(r.entry.id))
+                continue;
+            if (usedP + r.tokens > effBudget)
+                continue;
+            selectedItems.push(r);
+            selectedIds.add(r.entry.id);
+            usedP += r.tokens;
+        }
+        totalTokens = usedP;
+    }
+    else if (query === '*') {
+        // No query: return strongest memories by strength, up to budget.
+        const now = new Date();
+        const localRanked = localEntries
+            .map((e) => ({
+            entry: e,
+            score: calculateStrength(e, now),
+            tokens: estimateTokens(e.content),
+            isGlobal: false,
+        }))
+            .sort((a, b) => b.score - a.score);
+        const globalRanked = globalEntries
+            .map((e) => ({
+            entry: e,
+            score: calculateStrength(e, now) * (1 / 1.2),
+            tokens: estimateTokens(e.content),
+            isGlobal: true,
+        }))
+            .sort((a, b) => b.score - a.score);
+        const combined = [...localRanked, ...globalRanked].sort((a, b) => b.score - a.score);
+        let used = 0;
+        for (const r of combined) {
+            if (used + r.tokens > budget)
+                continue;
+            selectedItems.push(r);
+            used += r.tokens;
+        }
+        totalTokens = used;
+    }
+    else {
+        // Real query: hybrid search (global + local) or physics+hybrid (local only).
+        let results;
+        if (hasGlobal) {
+            const merged = await searchBothHybrid(query, ctx.hippoRoot, globalRoot, {
+                budget,
+                scope: activeScope,
+                tenantId: ctx.tenantId,
+            });
+            const localIndex = loadIndex(ctx.hippoRoot);
+            results = merged.map((r) => ({
+                entry: r.entry,
+                score: r.score,
+                tokens: r.tokens,
+                isGlobal: !localIndex.entries[r.entry.id],
+            }));
+        }
+        else {
+            const ctxConfig = loadConfig(ctx.hippoRoot);
+            const usePhysicsCtx = ctxConfig.physics?.enabled !== false;
+            const ctxResults = usePhysicsCtx
+                ? await physicsSearch(query, localEntries, {
+                    budget,
+                    hippoRoot: ctx.hippoRoot,
+                    physicsConfig: ctxConfig.physics,
+                    scope: activeScope,
+                })
+                : await hybridSearch(query, localEntries, {
+                    budget,
+                    hippoRoot: ctx.hippoRoot,
+                    scope: activeScope,
+                });
+            results = ctxResults.map((r) => ({
+                entry: r.entry,
+                score: r.score,
+                tokens: r.tokens,
+                isGlobal: false,
+            }));
+        }
+        selectedItems = results;
+        totalTokens = results.reduce((sum, r) => sum + r.tokens, 0);
+        // A5 H4: emit recall audit row for context-mode searches (matches the
+        // 'recall' op emitted by api.recall for parity). pinnedOnly + '*' fallback
+        // never hit the search engines, so they don't emit (matches cmdContext).
+        const ctxRecallMetadata = {
+            query: query.slice(0, 200),
+            results: selectedItems.length,
+            mode: 'context',
+        };
+        if (hasLocal) {
+            const localDb = openHippoDb(ctx.hippoRoot);
+            try {
+                appendAuditEvent(localDb, {
+                    tenantId: ctx.tenantId,
+                    actor: ctx.actor,
+                    op: 'recall',
+                    metadata: ctxRecallMetadata,
+                });
+            }
+            finally {
+                closeHippoDb(localDb);
+            }
+        }
+        if (hasGlobal) {
+            const globalDb = openHippoDb(globalRoot);
+            try {
+                appendAuditEvent(globalDb, {
+                    tenantId: ctx.tenantId,
+                    actor: ctx.actor,
+                    op: 'recall',
+                    metadata: ctxRecallMetadata,
+                });
+            }
+            finally {
+                closeHippoDb(globalDb);
+            }
+        }
+    }
+    if (limit < selectedItems.length) {
+        selectedItems = selectedItems.slice(0, limit);
+        totalTokens = selectedItems.reduce((sum, r) => sum + r.tokens, 0);
+    }
+    if (selectedItems.length === 0 &&
+        !activeSnapshot &&
+        !sessionHandoff &&
+        recentSessionEvents.length === 0) {
+        return { entries: [], tokens: 0 };
+    }
+    // pinnedOnly is the UserPromptSubmit hot path — read-only so pinned
+    // memories don't inflate retrieval_count or extend half_life by 2 days per
+    // turn over a long session.
+    if (!pinnedOnly) {
+        const toUpdate = selectedItems.map((s) => s.entry);
+        const updatedEntries = markRetrieved(toUpdate);
+        const localIndex = loadIndex(ctx.hippoRoot);
+        for (const u of updatedEntries) {
+            const targetRoot = localIndex.entries[u.id]
+                ? ctx.hippoRoot
+                : hasGlobal
+                    ? globalRoot
+                    : ctx.hippoRoot;
+            writeEntry(targetRoot, u);
+        }
+        localIndex.last_retrieval_ids = updatedEntries.map((u) => u.id);
+        saveIndex(ctx.hippoRoot, localIndex);
+        updateStats(ctx.hippoRoot, { recalled: selectedItems.length });
+        // Replace selectedItems entries with markRetrieved-updated copies so
+        // the returned ContextResult reflects post-recall state.
+        selectedItems = selectedItems.map((s) => ({
+            ...s,
+            entry: updatedEntries.find((u) => u.id === s.entry.id) ?? s.entry,
+        }));
+    }
+    return {
+        entries: selectedItems,
+        tokens: totalTokens,
+        activeSnapshot: activeSnapshot ?? undefined,
+        sessionHandoff: sessionHandoff ?? undefined,
+        recentEvents: recentSessionEvents.length > 0 ? recentSessionEvents : undefined,
+    };
+}
+/**
+ * Run the pure-storage consolidation pipeline.
+ *
+ * Tenant scope note: sleep operates on the WHOLE hippoRoot (all tenants in
+ * it), matching the pre-refactor cmdSleepCore behavior. Correct for a CLI
+ * maintenance op invoked by the operator. But once Episode B exposes this
+ * over HTTP `/v1/sleep`, the route MUST gate to a global-admin actor or
+ * scope dedup/audit/delete by ctx.tenantId — otherwise a tenant-A Bearer
+ * could dedupe and delete tenant-B's rows. See TODOS.md "Episode A
+ * follow-ups" for the Episode B preflight checklist.
+ *
+ * Audit emission gap: the consolidation phases (dedup, audit-delete) do
+ * NOT emit audit_log rows today, matching pre-refactor cmdSleepCore. Same
+ * CLI/MCP parity gap that T6 fixed for cmdOutcome, now visible at the api
+ * surface. Episode B should decide whether `/v1/sleep` writes a single
+ * 'consolidate' audit row per invocation or per-phase rows per deletion.
+ */
+export async function sleep(ctx, opts = {}) {
+    const dryRun = Boolean(opts.dryRun);
+    // Phase 1: Consolidation.
+    const consolidateResult = await consolidate(ctx.hippoRoot, { dryRun });
+    const result = {
+        active: consolidateResult.decayed,
+        removed: consolidateResult.removed,
+        mergedEpisodic: consolidateResult.merged,
+        newSemantic: consolidateResult.semanticCreated,
+        dryRun,
+        details: consolidateResult.details,
+    };
+    if (dryRun)
+        return result;
+    // Phase 2: Dedup (post-consolidate near-duplicate cleanup).
+    const dedupResult = deduplicateStore(ctx.hippoRoot);
+    if (dedupResult.removed > 0) {
+        const semDups = dedupResult.pairs.filter((p) => p.keptLayer === 'semantic' && p.removedLayer === 'semantic').length;
+        const epiDups = dedupResult.pairs.filter((p) => p.keptLayer === 'episodic' && p.removedLayer === 'episodic').length;
+        const crossDups = dedupResult.pairs.filter((p) => p.keptLayer !== p.removedLayer).length;
+        result.deduped = {
+            removed: dedupResult.removed,
+            semDups,
+            epiDups,
+            crossDups,
+        };
+    }
+    // Phase 3: Quality audit (remove junk, report warnings).
+    const allEntries = loadAllEntries(ctx.hippoRoot);
+    const auditOut = auditMemories(allEntries);
+    if (auditOut.issues.length > 0) {
+        const errors = auditOut.issues.filter((i) => i.severity === 'error');
+        const warnings = auditOut.issues.filter((i) => i.severity === 'warning');
+        if (errors.length > 0) {
+            for (const issue of errors) {
+                deleteEntry(ctx.hippoRoot, issue.memoryId);
+            }
+        }
+        if (errors.length > 0 || warnings.length > 0) {
+            result.audit = {
+                errorsRemoved: errors.length,
+                warningCount: warnings.length,
+            };
+        }
+    }
+    // Phase 4: Auto-share high-transfer-score memories to global.
+    if (!opts.noShare) {
+        const sleepConfig = loadConfig(ctx.hippoRoot);
+        if (sleepConfig.autoShareOnSleep) {
+            const shared = autoShare(ctx.hippoRoot, { minScore: 0.6 });
+            if (shared.length > 0) {
+                result.shared = shared.length;
+            }
+        }
+    }
+    // Phase 5: Post-sleep ambient state summary.
+    const postSleepConfig = loadConfig(ctx.hippoRoot);
+    if (postSleepConfig.ambient.enabled) {
+        const postSleepEntries = loadAllEntries(ctx.hippoRoot).filter((e) => !e.superseded_by);
+        if (postSleepEntries.length > 0) {
+            result.ambient = computeAmbientState(postSleepEntries);
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// outcomeForLastRecall (last-recall wrapper around outcome — Task 3)
+// ---------------------------------------------------------------------------
+/**
+ * Apply an outcome to the ids most recently returned by `recall()`.
+ *
+ * Reads `loadIndex(ctx.hippoRoot).last_retrieval_ids` (per-hippoRoot local
+ * state; not tenant-scoped at the index layer) and forwards to `outcome()`,
+ * which DOES tenant-filter via `readEntry(..., ctx.tenantId)` — cross-tenant
+ * ids in `last_retrieval_ids` are silently skipped, matching the MCP
+ * `hippo_outcome` semantics.
+ *
+ * Do NOT tighten `loadIndex` with `tenantId` inside this helper — doing so
+ * would break the (correct) cross-tenant-silent-skip behavior covered by
+ * the test in `tests/api-outcome-for-last-recall.test.ts`.
+ */
+export function outcomeForLastRecall(ctx, good) {
+    const idx = loadIndex(ctx.hippoRoot);
+    const ids = idx.last_retrieval_ids;
+    if (ids.length === 0)
+        return { applied: 0, ids: [] };
+    const { applied } = outcome(ctx, ids, good);
+    return { applied, ids };
+}
 //# sourceMappingURL=api.js.map