hippo-memory 1.60.0 → 1.62.0

package/dist/api/context.d.ts

@@ -0,0 +1,31 @@
+import { type MemoryEntry } from '../memory.js';
+import type { ContextOpts, ContextResult } from './context-types.js';
+import type { Context } from './types.js';
+export { oneCopyPerMemory } from './context-select.js';
+/**
+ * v39 S4: the secret half of the ambient policy on its own, for callers
+ * that apply their own scope rule. A flagged row is only admitted inside its owning project;
+ * flagged rows with no project origin never ambient-inject.
+ */
+export declare function ambientSecretAdmit(e: MemoryEntry, currentProjectName: string): boolean;
+/** Most rows per store a no-query context reads; past it, ranking and ambientState see the strongest by decay. */
+export declare const CONTEXT_CANDIDATE_CAP = 2000;
+/**
+ * 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>;
+//# sourceMappingURL=context.d.ts.map

package/dist/api/context.js

@@ -0,0 +1,378 @@
+// Ambient context injection: the admission policy and getContext.
+import { isInitialized } from '../store/open.js';
+import { strengthenRetrieved } from '../store/entry-writes.js';
+import { loadRecallSearchEntries } from '../store/search-rows.js';
+import { DEFAULT_SEARCH_CANDIDATE_LIMIT } from '../store/rows.js';
+import { loadAmbientCandidates, loadContextCandidates, } from '../store/candidates.js';
+import { loadIndex, saveIndex, updateStats } from '../store/index-and-stats.js';
+import { loadFreshActiveTaskSnapshot, listSessionEvents, SNAPSHOT_AMBIENT_MAX_AGE_MS } from '../store/sessions.js';
+import { loadLatestHandoff } from '../store/handoffs.js';
+import { estimateTokens } from '../token-ledger.js';
+import { markRetrieved, COMPACTION_MEMORY_TAG } from '../memory.js';
+import { isContentWorthStoring } from '../audit.js';
+import { getGlobalRoot } from '../shared.js';
+import { writeRecallTraceAtRoot } from '../recall-trace.js';
+import { evalNow, isRecallBoostAblated } from '../ablation.js';
+import { dropHeldCopies } from '../same-text.js';
+import { loadConfig } from '../config.js';
+import { resolveProjectIdentity, classifyOriginProject, isGlobalStoreRoot } from '../project-identity.js';
+import { promptTokens } from '../prompt-recall.js';
+import { detectSecret } from '../secret-detect.js';
+import { isSessionDigestRow } from '../session-digest.js';
+import { addAmbientTallies, ambientStateFromTallies } from '../ambient.js';
+import { loadAmbientTallies } from '../ambient-store.js';
+import { passesScopeFilterForRecall, assertScopeRequestAllowed } from '../recall-scope.js';
+import { finiteOr, selectBySearch, selectPinned, selectStrongest, } from './context-select.js';
+export { oneCopyPerMemory } from './context-select.js';
+/**
+ * v39: the single ambient-injection admission policy, shared by getContext
+ * and the CLI-side ambient-state summary so the two cannot drift.
+ *
+ * - S4 secret veto is UNCONDITIONAL: neither crossProject nor
+ *   contextProjectIsolation:false re-includes secrets. A flagged row only
+ *   injects inside its owning project; flagged rows with no project origin
+ *   (''/null) never ambient-inject at all. Explicit recall is unaffected -
+ *   recalling a secret is a deliberate act.
+ * - S2 envelope parity: private/quarantine scopes never inject unless `exactScope` names one.
+ * - S3 origin partition: other-project rows are excluded unless
+ *   `includeCrossProject`.
+ */
+function ambientAdmitEntry(e, currentProjectName, includeCrossProject, exactScope) {
+    if (!ambientSecretAdmit(e, currentProjectName))
+        return false;
+    if (!passesScopeFilterForRecall(e.scope ?? null, exactScope))
+        return false;
+    if (includeCrossProject)
+        return true;
+    return classifyOriginProject(e.origin_project, currentProjectName) !== 'cross-project';
+}
+/**
+ * v39 S4: the secret half of the ambient policy on its own, for callers
+ * that apply their own scope rule. A flagged row is only admitted inside its owning project;
+ * flagged rows with no project origin never ambient-inject.
+ */
+export function ambientSecretAdmit(e, currentProjectName) {
+    if (!detectSecret(e).flagged)
+        return true;
+    const origin = e.origin_project;
+    if (origin === undefined || origin === null || origin === '')
+        return false;
+    return origin === currentProjectName;
+}
+/** Most rows per store a no-query context reads; past it, ranking and ambientState see the strongest by decay. */
+export const CONTEXT_CANDIDATE_CAP = 2000;
+// The pinned-only branch needs pins and recent-N candidates, not the corpus; `recall` applies there only.
+function loadAmbientEntries(hippoRoot, tenantId, pinnedOnly, includeRecent, admit, window, recall, onQualityDrop) {
+    if (!pinnedOnly) {
+        const rows = 'query' in window
+            ? loadRecallSearchEntries(hippoRoot, window.query, DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId, window.exactScope, 'exact', false, window.project)
+            : loadContextCandidates(hippoRoot, tenantId, window);
+        return { entries: rows.filter(admit) };
+    }
+    // DF3's quality floor runs on the recent-N slice AFTER this load, so the load
+    // counts by it too, or it stops short of a store whose newest rows are junk.
+    const admitAmbient = (e) => {
+        if (!admit(e))
+            return false;
+        if (e.pinned || isContentWorthStoring(e.content))
+            return true;
+        onQualityDrop?.(e);
+        return false;
+    };
+    return loadAmbientCandidates(hippoRoot, tenantId, includeRecent, admitAmbient, recall);
+}
+/**
+ * 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 budget = opts.budget ?? 1500;
+    assertScopeRequestAllowed(ctx.actor, opts.exactScope);
+    if (budget <= 0) {
+        return { entries: [], tokens: 0 };
+    }
+    const plan = planContext(ctx, opts);
+    const sections = loadTaskSections(ctx, opts, plan, openBlockBudget(plan, opts, budget));
+    const admission = ambientAdmission(opts, plan, sections.shownHandoff);
+    const pools = loadPools(ctx, plan, admission, promptRecallRequest(opts, plan));
+    const noSections = !sections.shownSnapshot && !sections.shownHandoff && sections.shownEvents.length === 0;
+    if (!plan.promptRecallPending && pools.local.entries.length === 0 && pools.global.entries.length === 0 && noSections) {
+        return { entries: [], tokens: 0 };
+    }
+    const picked = plan.pinnedOnly
+        ? selectPinned(ctx, opts, plan, sections.left, pools, admission)
+        : plan.query === '*'
+            ? selectStrongest(plan, sections.left, pools)
+            : await selectBySearch(ctx, plan, sections.left, pools, admission);
+    if (picked === null) {
+        return { entries: [], tokens: 0 };
+    }
+    const { items, tokens } = finalizeSelection(picked, plan);
+    if (items.length === 0 && noSections) {
+        // A query that found nothing is the coverage-gap signal, so it still gets a trace; pinned-only stays read-only.
+        if (!plan.pinnedOnly)
+            traceEmptyContext(ctx, opts, plan.query);
+        return { entries: [], tokens: 0 };
+    }
+    // pinnedOnly is the UserPromptSubmit hot path — read-only so pinned
+    // memories don't inflate retrieval_count or extend half_life every turn.
+    const recorded = plan.pinnedOnly
+        ? { items, ambientState: undefined }
+        : recordRetrieval(ctx, opts, plan, items, sections.activeSnapshot);
+    return {
+        entries: recorded.items,
+        tokens,
+        activeSnapshot: sections.shownSnapshot ?? undefined,
+        sessionHandoff: sections.shownHandoff ?? undefined,
+        recentEvents: sections.shownEvents.length > 0 ? sections.shownEvents : undefined,
+        ambientState: recorded.ambientState,
+    };
+}
+function planContext(ctx, opts) {
+    const pinnedOnly = opts.pinnedOnly === true;
+    // Global memories do not establish a project boundary for task state.
+    const hasLocal = isInitialized(ctx.hippoRoot);
+    const query = (opts.q ?? '').trim() || '*';
+    const globalRoot = getGlobalRoot();
+    const hasGlobal = isInitialized(globalRoot);
+    const primaryIsGlobal = isGlobalStoreRoot(ctx.hippoRoot);
+    // opts.scope is only the tag boost, opts.exactScope the envelope request; other-project memories are
+    // excluded unless the caller asks for them (crossProject) or isolation is disabled.
+    const config = loadConfig(ctx.hippoRoot);
+    const isolationEnabled = config.contextProjectIsolation !== false;
+    const currentProjectName = opts.currentProject ?? resolveProjectIdentity(process.cwd()).name;
+    const includeCrossProject = opts.crossProject === true || !isolationEnabled;
+    // Decided before the ambient loads so the pinned-only FTS candidate query can share their connection.
+    const promptRecallPending = pinnedOnly && Boolean(opts.prompt?.trim()) && config.pinnedInject.promptRecall === true;
+    const cost = opts.cost;
+    const price = (entry, isGlobal, promptRecall) => cost
+        ? cost.entry({ entry, isGlobal, promptRecall, origin: entry.origin_project ?? null, category: classifyOriginProject(entry.origin_project, currentProjectName) })
+        : estimateTokens(entry.content);
+    return {
+        pinnedOnly,
+        limit: opts.limit ?? Number.POSITIVE_INFINITY,
+        includeRecent: opts.includeRecent ?? 0,
+        activeScope: opts.scope ?? '',
+        exactScope: opts.exactScope || undefined,
+        query,
+        hasLocal,
+        hasGlobal,
+        globalRoot,
+        primaryIsGlobal,
+        hasLocalTaskState: hasLocal && !primaryIsGlobal,
+        config,
+        currentProjectName,
+        includeCrossProject,
+        originProject: includeCrossProject || currentProjectName === '' ? undefined : currentProjectName,
+        promptRecallPending,
+        cost,
+        price,
+        obs: opts.deliveryObserver,
+    };
+}
+/** The prompt-recall candidate request the ambient loads carry, when the prompt has any terms. */
+function promptRecallRequest(opts, plan) {
+    const { pinnedInject } = plan.config;
+    const promptRecallTerms = plan.promptRecallPending && pinnedInject.enabled
+        ? Array.from(promptTokens(opts.prompt ?? ''))
+        : [];
+    return promptRecallTerms.length > 0
+        ? { terms: promptRecallTerms, limit: Math.floor(finiteOr(pinnedInject.promptRecallCandidates, 100, 1)) }
+        : undefined;
+}
+/** Reports the block's facts to the observer and returns the budget left after the fixed headers. */
+function openBlockBudget(plan, opts, budget) {
+    const { config, cost, obs, pinnedOnly, promptRecallPending } = plan;
+    const blockBudget = pinnedOnly && opts.budget === undefined ? config.pinnedInject.budget : budget;
+    obs?.facts({ projectName: plan.currentProjectName, budgetTokens: blockBudget, promptRecall: promptRecallPending });
+    if (pinnedOnly && !config.pinnedInject.enabled)
+        obs?.disabled();
+    return cost
+        ? Math.max(0, blockBudget - cost.fixed(blockBudget, { cross: plan.includeCrossProject, promptRecall: promptRecallPending, ambient: !pinnedOnly && config.ambient.enabled }))
+        : blockBudget;
+}
+// Sections print ahead of the memories, so they are paid first; one that does not fit is dropped, as an oversize entry is.
+function loadTaskSections(ctx, opts, plan, startLeft) {
+    const { exactScope, hasLocalTaskState, cost } = plan;
+    let left = startLeft;
+    const pays = (tokens) => {
+        if (tokens > left)
+            return false;
+        left -= tokens;
+        return true;
+    };
+    // Bounded read: an orphaned snapshot ages out of this ambient surface; the owner session's read stays unbounded.
+    const rowScope = (r) => r?.scope ?? null;
+    const rawActiveSnapshot = hasLocalTaskState
+        ? loadFreshActiveTaskSnapshot(ctx.hippoRoot, ctx.tenantId, {
+            sessionId: opts.currentSessionId,
+        })
+        : null;
+    // The same envelope rule ambientAdmitEntry applies to memory rows.
+    const activeSnapshot = rawActiveSnapshot && passesScopeFilterForRecall(rowScope(rawActiveSnapshot), exactScope)
+        ? rawActiveSnapshot
+        : null;
+    // Key on the RAW snapshot: a scope-hidden active session must not fall through to another session's ambient handoff.
+    const rawSessionHandoff = !hasLocalTaskState
+        ? null
+        : rawActiveSnapshot?.session_id
+            ? loadLatestHandoff(ctx.hippoRoot, ctx.tenantId, rawActiveSnapshot.session_id)
+            : loadLatestHandoff(ctx.hippoRoot, ctx.tenantId, undefined, {
+                unfinishedOnly: true,
+                maxAgeMs: SNAPSHOT_AMBIENT_MAX_AGE_MS,
+                // Scope is admitted in SQL so a newer denied row can't hide an older eligible one before LIMIT 1.
+                scopeFilter: 'default-deny',
+            });
+    const sessionHandoff = rawSessionHandoff && passesScopeFilterForRecall(rowScope(rawSessionHandoff), exactScope)
+        ? rawSessionHandoff
+        : null;
+    // Raw session id here too: each event is admitted on its own scope, same as recall and the CLI.
+    const recentSessionEvents = hasLocalTaskState && rawActiveSnapshot?.session_id
+        ? listSessionEvents(ctx.hippoRoot, ctx.tenantId, {
+            session_id: rawActiveSnapshot.session_id,
+            limit: 5,
+        }).filter((e) => passesScopeFilterForRecall(rowScope(e), exactScope))
+        : [];
+    const shownSnapshot = activeSnapshot && (!cost || pays(cost.snapshot(activeSnapshot))) ? activeSnapshot : null;
+    const shownHandoff = sessionHandoff && (!cost || pays(cost.handoff(sessionHandoff))) ? sessionHandoff : null;
+    const shownEvents = recentSessionEvents.length > 0 && (!cost || pays(cost.trail(recentSessionEvents))) ? recentSessionEvents : [];
+    plan.obs?.sections(Number(shownSnapshot !== null) + Number(shownHandoff !== null) + Number(shownEvents.length > 0), Number(activeSnapshot !== shownSnapshot) + Number(sessionHandoff !== shownHandoff) + Number(recentSessionEvents.length !== shownEvents.length));
+    return { activeSnapshot, shownSnapshot, shownHandoff, shownEvents, left };
+}
+function ambientAdmission(opts, plan, shownHandoff) {
+    const transcriptHandoffSession = shownHandoff?.evidence?.derivedFrom === 'transcript' ? shownHandoff.sessionId : null;
+    let digestHiddenForHandoff = false;
+    const ambientAdmit = (e) => {
+        // A printed handoff already carries the session's closing message, which its digest would print a second time.
+        if (transcriptHandoffSession !== null && e.source_session_id === transcriptHandoffSession && isSessionDigestRow(e)) {
+            digestHiddenForHandoff = true;
+            return false;
+        }
+        return ambientAdmitEntry(e, plan.currentProjectName, plan.includeCrossProject, plan.exactScope);
+    };
+    const ownSessionId = opts.currentSessionId || '';
+    // Inside admit, not after the load, so the loader's window widens past a session's own items.
+    const isOwnCompactionItem = (e) => ownSessionId !== '' &&
+        e.source_session_id === ownSessionId &&
+        e.tags.includes(COMPACTION_MEMORY_TAG);
+    // Superseded rows never inject; which rows reach ambientAdmitEntry matters because it regex-scans content for secrets.
+    const admit = (e) => !e.superseded_by && !isOwnCompactionItem(e) && ambientAdmit(e);
+    // The two-store search has always ranked a session's own compaction items; only the local search drops them.
+    const bothStoresAdmit = (e) => !e.superseded_by && ambientAdmit(e);
+    return { ambientAdmit, admit, bothStoresAdmit, digestHidden: () => digestHiddenForHandoff };
+}
+function loadPools(ctx, plan, admission, recallRequest) {
+    const { obs, pinnedOnly, primaryIsGlobal, hasGlobal, exactScope } = plan;
+    const searches = plan.query !== '*' && !pinnedOnly;
+    const searchesBoth = searches && hasGlobal && !primaryIsGlobal;
+    const poolAdmit = searchesBoth ? admission.bothStoresAdmit : admission.admit;
+    const loadAdmit = obs ? obs.watchAdmit(poolAdmit) : poolAdmit;
+    const qualityDrop = (isGlobal) => obs && !plan.promptRecallPending ? (e) => obs.qualityDropped(e, isGlobal) : undefined;
+    // The window's predicates are ones admit applies anyway, so below the cap the admitted rows are unchanged.
+    const window = searches
+        ? { query: plan.query, exactScope, project: plan.originProject }
+        : {
+            exactScope,
+            project: plan.originProject,
+            cap: CONTEXT_CANDIDATE_CAP,
+            now: evalNow(),
+        };
+    // Tenant-scoped loads: never resolveTenantId({}) here.
+    const local = plan.hasLocal
+        ? loadAmbientEntries(ctx.hippoRoot, ctx.tenantId, pinnedOnly, plan.includeRecent, loadAdmit, window, recallRequest, qualityDrop(primaryIsGlobal))
+        : { entries: [] };
+    const global = hasGlobal && !primaryIsGlobal
+        ? loadAmbientEntries(plan.globalRoot, ctx.tenantId, pinnedOnly, plan.includeRecent, loadAdmit, window, recallRequest, qualityDrop(true))
+        : { entries: [] };
+    return { local, global };
+}
+/** The `limit` cut, then the held-copy drop, then each entry's origin annotation. */
+function finalizeSelection(picked, plan) {
+    const { obs } = plan;
+    let selected = picked;
+    if (plan.limit < selected.length) {
+        const cut = selected.slice(0, plan.limit);
+        obs?.dropMissing(selected.map((r) => r.entry), cut.map((r) => r.entry), 'limit', 'limit');
+        selected = cut;
+    }
+    const heldDropped = dropHeldCopies(selected, (r) => r.entry); // after the last cut, so a merged row that was cut hides nothing
+    obs?.dropMissing(selected.map((r) => r.entry), heldDropped.map((r) => r.entry), 'limit', 'duplicate');
+    selected = heldDropped;
+    const tokens = selected.reduce((sum, r) => sum + r.tokens, 0);
+    // Every returned entry carries its origin and how it relates to the active project, so renderers can mark cross-project rows.
+    selected = selected.map((r) => ({
+        ...r,
+        origin: r.entry.origin_project ?? null,
+        category: classifyOriginProject(r.entry.origin_project, plan.currentProjectName),
+    }));
+    obs?.selected(selected);
+    return { items: selected, tokens };
+}
+// Never touches the index, so it cannot desync last_retrieval_ids from last_trace_id; fail-soft, never throws.
+function traceEmptyContext(ctx, opts, query) {
+    // No snapshot in this branch, so the caller's own id is the only session to stamp.
+    writeRecallTraceAtRoot(ctx.hippoRoot, {
+        tenantId: ctx.tenantId,
+        sessionId: opts.currentSessionId || null,
+        pipeline: 'context',
+        query,
+        explainMode: false,
+        results: [],
+    });
+}
+/** Strengthens and marks the returned rows, then writes the trace and index together. */
+function recordRetrieval(ctx, opts, plan, selected, activeSnapshot) {
+    const toUpdate = selected.map((s) => s.entry);
+    const updatedEntries = markRetrieved(toUpdate);
+    const localIndex = loadIndex(ctx.hippoRoot);
+    const retrievedIds = updatedEntries.map((u) => u.id);
+    const strengthenedHere = strengthenRetrieved(ctx.hippoRoot, retrievedIds, { recallBoostAblated: isRecallBoostAblated() });
+    if (plan.hasGlobal)
+        strengthenRetrieved(plan.globalRoot, retrievedIds.filter((id) => !strengthenedHere.has(id)), { recallBoostAblated: isRecallBoostAblated() });
+    localIndex.last_retrieval_ids = retrievedIds;
+    // Trace first on its own short-lived connection, then fold its id into localIndex so one saveIndex moves
+    // last_retrieval_ids and last_trace_id in lockstep; a failed trace write stores null, never a stale id.
+    const traceId = writeRecallTraceAtRoot(ctx.hippoRoot, {
+        tenantId: ctx.tenantId,
+        sessionId: opts.currentSessionId || activeSnapshot?.session_id || null,
+        pipeline: 'context',
+        query: plan.query,
+        explainMode: false,
+        results: selected.map((s) => ({
+            memoryId: s.entry.id,
+            score: s.score,
+        })),
+    });
+    localIndex.last_trace_id = traceId !== null ? String(traceId) : null;
+    saveIndex(ctx.hippoRoot, localIndex);
+    updateStats(ctx.hippoRoot, { recalled: selected.length });
+    // Replace selectedItems entries with markRetrieved-updated copies so
+    // the returned ContextResult reflects post-recall state.
+    const items = selected.map((s) => ({
+        ...s,
+        entry: updatedEntries.find((u) => u.id === s.entry.id) ?? s.entry,
+    }));
+    // Read after strengthenRetrieved commits, so the rows just retrieved count at their new strength.
+    return { items, ambientState: plan.config.ambient.enabled ? readAmbientState(ctx, plan) : undefined };
+}
+function readAmbientState(ctx, plan) {
+    const filter = { exactScope: plan.exactScope, project: plan.originProject, currentProject: plan.currentProjectName, now: evalNow() };
+    const roots = [...(plan.hasLocal ? [ctx.hippoRoot] : []), ...(plan.hasGlobal && !plan.primaryIsGlobal ? [plan.globalRoot] : [])];
+    const tallies = roots.map((root) => loadAmbientTallies(root, ctx.tenantId, filter));
+    const total = tallies.length > 0 ? tallies.reduce(addAmbientTallies) : undefined;
+    return total && total.total > 0 ? ambientStateFromTallies(total) : undefined;
+}
+//# sourceMappingURL=context.js.map

package/dist/api/dormant.d.ts

@@ -0,0 +1,30 @@
+import { type DormantMemory, type ListDormantOpts } from '../dormant.js';
+import { type MemoryEntry } from '../memory.js';
+import type { Context } from './types.js';
+/**
+ * A tenant's dormant memories (src/dormant.ts): what sleep moved out of
+ * active memory instead of deleting, when `dormant.enabled` is on. Newest
+ * first; `opts.query` keeps rows containing every term (case-insensitive).
+ */
+export declare function listDormant(ctx: Context, opts?: ListDormantOpts): DormantMemory[];
+/**
+ * Bring a dormant memory back into active memory. It returns as if just
+ * recalled: `last_retrieved` is now, so it gets a full half-life before it
+ * can fade again. Every other field is the snapshot taken when it went
+ * dormant.
+ *
+ * Throws when the tenant has no dormant memory with that id (another
+ * tenant's id reads the same way), when a live memory already holds the id,
+ * and RejectedValueError when the value has been rejected since. On any
+ * throw the dormant copy stays where it is.
+ */
+export declare function restoreDormant(ctx: Context, id: string): MemoryEntry;
+/**
+ * Permanently delete a dormant memory: the explicit "forget it for good"
+ * that dormant storage leaves to the user. Throws when the tenant has no
+ * dormant memory with that id.
+ */
+export declare function forgetDormant(ctx: Context, id: string): void;
+/** Whether the tenant holds a dormant memory with this id (for "not found" hints). */
+export declare function isDormant(ctx: Context, id: string): boolean;
+//# sourceMappingURL=dormant.d.ts.map

package/dist/api/dormant.js

@@ -0,0 +1,140 @@
+// Dormant memories: list, restore, forget and check.
+import { openHippoDb, closeHippoDb } from '../db.js';
+import { ConflictError, NotFoundError } from '../api-errors.js';
+import { auditRejectionRefusal } from '../store/audit-event.js';
+import { stampOriginProject } from '../store/entry-row.js';
+import { writeEntryDbOnly, writeEntryMirrors } from '../store/entry-writes.js';
+import { updateStatsUnlessBusy } from '../store/index-and-stats.js';
+import { RejectedValueError } from '../rejection.js';
+import { listDormantRows, readDormantSnapshot, deleteDormantRow, hasDormantRow, } from '../dormant.js';
+import { createMemory, calculateStrength } from '../memory.js';
+import { appendAuditEvent, reportAuditWriteFailure } from '../audit.js';
+import { loadConfig } from '../config.js';
+/**
+ * A tenant's dormant memories (src/dormant.ts): what sleep moved out of
+ * active memory instead of deleting, when `dormant.enabled` is on. Newest
+ * first; `opts.query` keeps rows containing every term (case-insensitive).
+ */
+export function listDormant(ctx, opts = {}) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        return listDormantRows(db, ctx.tenantId, opts);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * Bring a dormant memory back into active memory. It returns as if just
+ * recalled: `last_retrieved` is now, so it gets a full half-life before it
+ * can fade again. Every other field is the snapshot taken when it went
+ * dormant.
+ *
+ * Throws when the tenant has no dormant memory with that id (another
+ * tenant's id reads the same way), when a live memory already holds the id,
+ * and RejectedValueError when the value has been rejected since. On any
+ * throw the dormant copy stays where it is.
+ */
+export function restoreDormant(ctx, id) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        let restored;
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            const dormant = readDormantSnapshot(db, ctx.tenantId, id);
+            if (!dormant) {
+                throw new NotFoundError(`dormant memory not found: ${id}`);
+            }
+            if (db.prepare(`SELECT 1 FROM memories WHERE id = ?`).get(id) !== undefined) {
+                throw new ConflictError(`memory ${id} is already active; forget it before restoring its dormant copy`);
+            }
+            const now = new Date();
+            // Dormant rows are long-lived, so a snapshot can predate a field added
+            // later: createMemory supplies a default for anything it lacks, then
+            // the snapshot overrides every field it does carry, content included.
+            // (The placeholder only satisfies createMemory's minimum length, so a
+            // legacy row shorter than 3 chars can still be restored.)
+            const revived = {
+                ...createMemory('dormant snapshot defaults', { baseHalfLifeDays: loadConfig(ctx.hippoRoot).defaultHalfLifeDays }),
+                ...dormant.entry,
+                last_retrieved: now.toISOString(),
+            };
+            restored = stampOriginProject(ctx.hippoRoot, { ...revived, strength: calculateStrength(revived, now) });
+            writeEntryDbOnly(db, restored, { actor: ctx.actor.subject });
+            deleteDormantRow(db, ctx.tenantId, id);
+            // A restore is a labelled "forgot it, then needed it" event: the
+            // signal a learned lifecycle (ROADMAP LC3) trains on. Same transaction
+            // as the restore, so the label exists exactly when the restore does.
+            appendAuditEvent(db, {
+                tenantId: ctx.tenantId,
+                actor: ctx.actor.subject,
+                op: 'dormant_restore',
+                targetId: id,
+                metadata: {
+                    reason: dormant.reason,
+                    strengthAtDormancy: dormant.strength,
+                    dormantAt: dormant.dormantAt,
+                    daysDormant: Math.max(0, (now.getTime() - Date.parse(dormant.dormantAt)) / (24 * 60 * 60 * 1000)),
+                },
+            });
+            db.exec('COMMIT');
+        }
+        catch (err) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { /* already rolled back */ }
+            if (err instanceof RejectedValueError) {
+                auditRejectionRefusal(db, err, ctx.actor.subject);
+            }
+            throw err;
+        }
+        writeEntryMirrors(ctx.hippoRoot, restored);
+        return restored;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * Permanently delete a dormant memory: the explicit "forget it for good"
+ * that dormant storage leaves to the user. Throws when the tenant has no
+ * dormant memory with that id.
+ */
+export function forgetDormant(ctx, id) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        if (!deleteDormantRow(db, ctx.tenantId, id)) {
+            throw new NotFoundError(`dormant memory not found: ${id}`);
+        }
+        try {
+            appendAuditEvent(db, {
+                tenantId: ctx.tenantId,
+                actor: ctx.actor.subject,
+                op: 'forget',
+                targetId: id,
+                metadata: { dormant: true },
+            });
+        }
+        catch (error) {
+            // Best-effort, like every other forget audit row: the delete stands.
+            reportAuditWriteFailure('forget', String(error), id);
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    // Counted like every other permanent removal (forget, archiveRaw).
+    updateStatsUnlessBusy(ctx.hippoRoot, { forgotten: 1 }, `removed ${id}`);
+}
+/** Whether the tenant holds a dormant memory with this id (for "not found" hints). */
+export function isDormant(ctx, id) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        return hasDormantRow(db, ctx.tenantId, id);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=dormant.js.map

package/dist/api/drill-down.d.ts

@@ -0,0 +1,84 @@
+import type { Context } from './types.js';
+export interface DrillDownOpts {
+    /** Cap on number of children returned. Default 50. */
+    limit?: number;
+    /**
+     * Optional token budget. When set, children are appended in chronological
+     * order (created ASC) until adding the next child would exceed the budget.
+     * Token cost = the child's printed line under `cost`, else ceil(content.length / 4).
+     *
+     * For depth > 1, the budget is GLOBAL cumulative (NOT per-level).
+     */
+    budget?: number;
+    /**
+     * v0.30 / E5 — walk N levels down (default 1 = direct children only).
+     * Higher values include children of children, etc. Internal hard cap 10
+     * to prevent pathological depth walks. BFS uses visited Set for dedup
+     * (defensive against shared-child data anomalies; DAG is acyclic by
+     * construction).
+     */
+    depth?: number;
+    cost?: DrillDownCost;
+}
+export interface DrillDownSummary {
+    id: string;
+    content: string;
+    descendantCount: number;
+    earliestAt: string | null;
+    latestAt: string | null;
+}
+export interface DrillDownChild {
+    id: string;
+    content: string;
+    layer: string;
+    dagLevel: number;
+    created: string;
+}
+export interface DrillDownCost {
+    child: (c: DrillDownChild) => number;
+    fixed: (summary: DrillDownSummary, widest: number) => number;
+}
+export interface DrillDownResult {
+    summary: DrillDownSummary;
+    children: DrillDownChild[];
+    totalChildren: number;
+    truncated: boolean;
+}
+/**
+ * v1.6.4 discriminated failure shape. Two reasons distinguishable:
+ *   - `not_found`: covers genuinely-missing, wrong-tenant, AND
+ *     scope-blocked (codex round 3 P1 — distinguishing scope_blocked
+ *     from not_found on non-HTTP surfaces leaked private-row existence
+ *     to no-scope callers, even though the HTTP route already collapsed
+ *     them. Collapse at the API layer.)
+ *   - `not_drillable`: id is a leaf row (level 0/1). Caller-actionable.
+ *
+ * If a future drillDown gains a `scope` opt for explicit-scope callers,
+ * a `scope_blocked` failure could be safely re-introduced ONLY for that
+ * code path (caller already proved authorization by passing a scope).
+ */
+export interface DrillDownFailure {
+    failure: 'not_found' | 'not_drillable';
+}
+export type DrillDownOutcome = DrillDownResult | DrillDownFailure;
+/**
+ * Walk one step down the DAG from a level-2 (or higher) summary to its direct
+ * children. Companion to `recall(... summarizeOverflow: true)` — when recall
+ * surfaces a summary with `substitutedFor: [...]`, the caller drills into the
+ * summary id to recover the original detail.
+ *
+ * Tenant scope: only summaries owned by `ctx.tenantId` are reachable. The same
+ * scope filter that recall applies is enforced on the children — a level-2
+ * summary in `slack:public:CGEN` cannot leak `slack:private:*` children even
+ * if the underlying DAG accidentally linked across scopes.
+ *
+ * Returns a discriminated `DrillDownOutcome`: `DrillDownResult` on success,
+ * or `{failure: '...'}` for `not_found` (covers genuinely-missing AND wrong-
+ * tenant, intentionally indistinguishable), `not_drillable` (id is a leaf
+ * row), or `scope_blocked` (caller has no scope grant for the row's scope).
+ *
+ * Pre-v1.6.4 returned null for all four cases. JS callers migrate via
+ * `'failure' in result` checks; HTTP route maps `not_drillable` to 422.
+ */
+export declare function drillDown(ctx: Context, summaryId: string, opts?: DrillDownOpts): DrillDownOutcome;
+//# sourceMappingURL=drill-down.d.ts.map