hippo-memory 1.11.2 → 1.11.3

package/dist/api.d.ts

@@ -9,9 +9,10 @@
 import { type DatabaseSyncLike } from './db.js';
 import { type TaskSnapshot, type SessionEvent } from './store.js';
 import type { SessionHandoff } from './handoff.js';
-import { type MemoryKind } from './memory.js';
+import { type MemoryKind, type MemoryEntry } from './memory.js';
 import { type AuditEvent, type AuditOp } from './audit.js';
 import { type ApiKeyListItem } from './auth.js';
+import { type AmbientState } from './ambient.js';
 export interface Context {
     hippoRoot: string;
     tenantId: string;
@@ -527,4 +528,134 @@ export interface AuditListOpts {
  * A5: cmdAuditList does not record a 'recall'-style read event).
  */
 export declare function auditList(ctx: Context, opts: AuditListOpts): AuditEvent[];
+/**
+ * Options for `getContext` — assemble a budget-bounded context bundle
+ * (recalled memories + active task snapshot + handoff + recent events).
+ * Extracted from `cmdContext` in `cli.ts` in Episode A of the api.ts refactor.
+ *
+ * Named `getContext` (not `context`) to avoid collision with the `Context`
+ * interface above and the ubiquitous `ctx: Context` convention. Follows the
+ * existing `getEntry` naming pattern in store.ts.
+ *
+ * Scope narrow (T5 execute decision): rendering opts (`format`, `framing`,
+ * `rendered`) and host-side opts (`auto`) are NOT included here. The print
+ * helpers (`printContextMarkdown`, `printActiveTaskSnapshot`, `printHandoff`,
+ * `printSessionEvents`) are shared with `cmdRecall` / `cmdSnapshot` /
+ * `cmdHandoffShow` — moving them into api.ts would expand T5 to also rewire
+ * those commands. CLI handles rendering + auto-resolution. Episode B can add
+ * `api.renderContext` once a shared rendering need actually materializes.
+ */
+export interface ContextOpts {
+    q?: string;
+    /** Default 1500 tokens. */
+    budget?: number;
+    limit?: number;
+    pinnedOnly?: boolean;
+    scope?: string;
+    includeRecent?: number;
+}
+export interface ContextResultEntry {
+    entry: MemoryEntry;
+    score: number;
+    tokens: number;
+    isGlobal?: boolean;
+    isFreshTail?: boolean;
+}
+export interface ContextResult {
+    entries: ContextResultEntry[];
+    tokens: number;
+    activeSnapshot?: TaskSnapshot | null;
+    sessionHandoff?: SessionHandoff | null;
+    recentEvents?: SessionEvent[];
+}
+/**
+ * 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 declare function getContext(ctx: Context, opts?: ContextOpts): Promise<ContextResult>;
+/**
+ * Options for `sleep` — run the pure-storage consolidation pipeline
+ * (consolidate + dedup + audit + share + ambient) and return structured counts.
+ *
+ * Extracted from `cmdSleepCore` Phase 2-6 in Episode A. NOT covered by api.sleep:
+ * the cli-only auto-learn phase (Phase 1: learnFromRepo + learnFromMemoryMd),
+ * which is intrinsically host-bound (uses `process.cwd()` / `os.homedir()`).
+ * Auto-learn stays in cli.ts cmdSleepCore as a pre-api block.
+ *
+ * The CLI `cmdSleep` wrapper continues to own the log-file tee + console
+ * rendering + `process.exit`; `api.sleep` is pure (no console.log, no IO
+ * beyond the store).
+ */
+export interface SleepOpts {
+    dryRun?: boolean;
+    noShare?: boolean;
+}
+export interface SleepResult {
+    active: number;
+    removed: number;
+    mergedEpisodic: number;
+    newSemantic: number;
+    dryRun: boolean;
+    deduped?: {
+        removed: number;
+        semDups: number;
+        epiDups: number;
+        crossDups: number;
+    };
+    audit?: {
+        errorsRemoved: number;
+        warningCount: number;
+    };
+    shared?: number;
+    ambient?: AmbientState | null;
+    details?: string[];
+}
+/**
+ * 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 declare function sleep(ctx: Context, opts?: SleepOpts): Promise<SleepResult>;
+/**
+ * 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 declare function outcomeForLastRecall(ctx: Context, good: boolean): {
+    applied: number;
+    ids: string[];
+};
 //# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/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