hippo-memory 1.55.0 → 1.57.0

package/README.md

@@ -548,6 +548,17 @@ crashed, shows what was sent only. Re-reads usually bill at the provider's cache
 a fraction of the full input price. Counts are estimates (characters / 4), the same estimate
 every budget uses. Rows older than 90 days are pruned.
 
+**See why a memory did or did not reach the agent.** Turn on the delivery ledger with
+`{"deliveryLedger":{"enabled":true}}` in `.hippo/config.json` (off by default). The flag is
+read from the store the token ledger writes to: the project's local store when it has one,
+else the global store. Each per-prompt hook call then records one event (session, turn
+number, whether the block was sent, reused, empty or disabled, counts and token totals) and
+one row per candidate memory: emitted, reused or rejected, with the stage and the
+reason it was dropped. With prompt recall on, recent memories dropped by the quality filter
+are not recorded yet. It holds ids, hashes, counts and reasons only, never prompt or memory
+text; the prompt hash is unsalted, so a very short prompt can be guessed. A ledger failure prints one stderr line and never changes what the hook prints. Rows
+older than 90 days are pruned; at a heavy 300 prompts a day that is about 190 MB per store.
+
 ---
 
 ### Outcome feedback

package/dist/api.d.ts

@@ -17,8 +17,9 @@ import { type SessionHandoff } from './handoff.js';
 import { type MemoryKind, type MemoryEntry } from './memory.js';
 import { auditMemories, type AuditEvent, type AuditOp } from './audit.js';
 import { autoShare } from './shared.js';
+import type { DeliveryObserver } from './delivery-recorder.js';
 import { type ApiKeyListItem } from './auth.js';
-import { type RerankStep } from './search.js';
+import { type RerankStep, type SearchResult } from './search.js';
 import { consolidate } from './consolidate.js';
 import { loadConfig } from './config.js';
 import { deduplicateStore } from './dedupe.js';
@@ -91,9 +92,8 @@ export type { TokenSummary, TokenSurface, TokenSurfaceSummary } from './token-le
 export type { FailureSummary } from './failure-log.js';
 export { classifyOriginProject } from './project-identity.js';
 /**
- * v39 S4: the secret half of the ambient policy on its own, for surfaces
- * with their own scope semantics (MCP hippo_context's explicit-scope
- * exact-match). A flagged row is only admitted inside its owning 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 declare function ambientSecretAdmit(e: MemoryEntry, currentProjectName: string): boolean;
@@ -269,16 +269,22 @@ export interface RecallOpts {
      * Mirrors `suppressAvailabilityHint`'s pattern: callers that run their OWN
      * tracing over a DIFFERENT result set must suppress api.recall's copy so
      * the training corpus doesn't get a trace mislabeled as 'api' pipeline
-     * when the caller's actual user-visible results came from elsewhere. The
-     * MCP handler sets this — its primary ranked band comes from a separate
-     * physics/hybrid scorer, not this api.recall call's BM25 band (real MCP
-     * tracing is the reserved 'mcp' pipeline, a follow-up). HTTP / direct SDK
-     * callers leave this unset and get the trace.
+     * when the caller's actual user-visible results came from elsewhere. Under
+     * `showRanked` it also drops the 'mcp' trace of the shown list. HTTP /
+     * direct SDK callers leave this unset and get the trace.
      */
     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. */
     keepHeldCopies?: boolean;
+    /** 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) => readonly string[];
+}
+/** `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 interface ContinuityBlock {
     activeSnapshot: TaskSnapshot | null;
@@ -945,6 +951,8 @@ export interface ContextOpts {
     limit?: number;
     pinnedOnly?: boolean;
     scope?: string;
+    /** Envelope scope to match exactly, as in `recall`: admits that scope even when private, after the actor's scope check. */
+    exactScope?: string;
     /** With `pinnedOnly`, also inject the N most recent writes that pass the
      *  quality floor (`isContentWorthStoring`, DF3). Filtering happens BEFORE
      *  the take-N, so a caller asking for 5 gets 5 qualifying entries rather
@@ -974,6 +982,8 @@ export interface ContextOpts {
     prompt?: string;
     /** What the budget pays for, from the caller that renders the block. Absent = the memory text alone. */
     cost?: ContextCost;
+    /** @internal The CLI's delivery-ledger observer; it only reads, so selection is the same with or without it. */
+    deliveryObserver?: DeliveryObserver;
 }
 /** Budget prices in the text a caller prints, so the budget bounds what reaches the model. */
 export interface ContextCost {

package/dist/api.js

@@ -16,7 +16,7 @@ import { detectInstruction } from './instruction-detect.js';
 import { quarantineScopeFor, recordQuarantine, getQuarantineRow, listQuarantineRows, approveQuarantineRow, rejectQuarantineRow, } from './quarantine.js';
 import { summarizeFailures } from './failure-log.js';
 import { formatHandoffEvidenceLine } from './handoff.js';
-import { createMemory, createSuccessor, applyOutcome, calculateStrength, CHURN_STALE_TAG, COMPACTION_MEMORY_TAG, } from './memory.js';
+import { createMemory, createSuccessor, applyOutcome, calculateStrength, markRetrieved, CHURN_STALE_TAG, COMPACTION_MEMORY_TAG, } from './memory.js';
 import { appendAuditEvent, auditQueryFields, queryAuditEvents, auditMemories, isContentWorthStoring, } from './audit.js';
 import { promoteToGlobal, getGlobalRoot, autoShare, searchBothHybrid } from './shared.js';
 import { writeRecallTrace, writeRecallTraceAtRoot, recordTraceOutcome } from './recall-trace.js';
@@ -24,7 +24,7 @@ import { evalNow } from './ablation.js';
 import { archiveRawMemory } from './raw-archive.js';
 import { createApiKey, listApiKeys, revokeApiKey, grantScope, ungrantScope, } from './auth.js';
 import { applyGoalStackBoost } from './goals.js';
-import { markRetrieved, estimateTokens, hybridSearch, physicsSearch, churnStaleFactor } from './search.js';
+import { estimateTokens, hybridSearch, physicsSearch, churnStaleFactor } from './search.js';
 import { compareEntryIdentity, compareScoredResults } from './compare.js';
 import { dropHeldCopies, duplicateKey, storedTextKeys } from './same-text.js';
 import { scopeMatch } from './scope.js';
@@ -39,7 +39,7 @@ import { computeAmbientState } from './ambient.js';
 import { loadPendingExtractionTenants, markPendingProcessedUpTo } from './graph.js';
 import { extractGraph } from './graph-extract.js';
 import { computePlanningFallacyOutput, } from './predictions.js';
-import { detectAnchoring, hashQueryText, } from './recall-history.js';
+import { detectAnchoring, hashQueryText, biasHintEnabled, } from './recall-history.js';
 import { detectAvailabilityBias } from './availability.js';
 /**
  * Helper for building process-local (admin-by-default) Actor values. v1.12.0
@@ -107,23 +107,22 @@ export { classifyOriginProject } from './project-identity.js';
  *   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 scopes + quarantine buckets never inject.
+ * - 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) {
+function ambientAdmitEntry(e, currentProjectName, includeCrossProject, exactScope) {
     if (!ambientSecretAdmit(e, currentProjectName))
         return false;
-    if (!passesScopeFilterForRecall(e.scope ?? null, undefined))
+    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 surfaces
- * with their own scope semantics (MCP hippo_context's explicit-scope
- * exact-match). A flagged row is only admitted inside its owning 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) {
@@ -135,12 +134,19 @@ export function ambientSecretAdmit(e, currentProjectName) {
     return origin === currentProjectName;
 }
 // The pinned-only branch needs pins and recent-N candidates, not the corpus; `recall` applies there only.
-function loadAmbientEntries(hippoRoot, tenantId, pinnedOnly, includeRecent, admit, recall) {
+function loadAmbientEntries(hippoRoot, tenantId, pinnedOnly, includeRecent, admit, recall, onQualityDrop) {
     if (!pinnedOnly)
         return { entries: loadAllEntries(hippoRoot, tenantId).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) => admit(e) && (e.pinned || isContentWorthStoring(e.content));
+    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);
 }
 // Share and promote copy a memory to the global store under a new id, so equal content is the only link.
@@ -237,6 +243,8 @@ export function recall(ctx, opts) {
 export async function retrieve(ctx, opts) {
     assertScopeRequestAllowed(ctx.actor, opts.scope);
     const windowSize = recallWindowSize(opts);
+    if (opts.showRanked)
+        return retrieveFromStore(ctx, opts, windowSize, opts.showRanked);
     let candidates = loadRecallSearchEntries(ctx.hippoRoot, opts.query, windowSize, ctx.tenantId, opts.scope, 'exact', false);
     if (opts.mode === 'hybrid' || opts.mode === 'physics') {
         const searchOpts = { budget: Infinity, hippoRoot: ctx.hippoRoot, scope: opts.scope ?? null };
@@ -250,6 +258,40 @@ export async function retrieve(ctx, opts) {
     strengthenRetrieved(ctx.hippoRoot, result.results.map((r) => r.id), ctx.tenantId);
     return result;
 }
+/** `retrieve` under `showRanked`: physics when `mode` says so, hybrid otherwise, over every admitted row. */
+async function retrieveFromStore(ctx, opts, windowSize, show) {
+    const store = loadAllEntries(ctx.hippoRoot, ctx.tenantId);
+    const pool = store.filter((e) => passesScopeFilterForRecall(e.scope ?? null, opts.scope));
+    // No scope option: the scope boost follows HIPPO_SCOPE and the skill env, as MCP recall always ranked.
+    const searchOpts = { budget: Infinity, hippoRoot: ctx.hippoRoot };
+    let ranked = opts.mode === 'physics'
+        ? await physicsSearch(opts.query, pool, { ...searchOpts, physicsConfig: loadConfig(ctx.hippoRoot).physics })
+        : await hybridSearch(opts.query, pool, searchOpts);
+    if (opts.sessionId && !opts.goalTag) {
+        const db = openHippoDb(ctx.hippoRoot);
+        try {
+            ranked = applyGoalStackBoost(db, ranked, { sessionId: opts.sessionId, tenantId: ctx.tenantId, limit: ranked.length });
+        }
+        finally {
+            closeHippoDb(db);
+        }
+    }
+    const window = ranked.slice(0, windowSize).map((r) => r.entry);
+    const result = recallFrom(ctx, { ...opts, suppressRecallTrace: true }, windowSize, window);
+    const shown = show({ ranked, pool, droppedByScope: store.length - pool.length }, result);
+    strengthenRetrieved(ctx.hippoRoot, shown, ctx.tenantId);
+    if (!opts.suppressRecallTrace) {
+        const scores = new Map(ranked.map((r) => [r.entry.id, r.score]));
+        writeRecallTraceAtRoot(ctx.hippoRoot, {
+            tenantId: ctx.tenantId,
+            sessionId: opts.sessionId ?? null,
+            pipeline: 'mcp',
+            query: opts.query,
+            results: shown.map((id) => ({ memoryId: id, score: scores.get(id) ?? 0 })),
+        });
+    }
+    return result;
+}
 /** Contract preflight: throws before any store-touching work. */
 function recallWindowSize(opts) {
     // F5 (v1.6.5) preflight — codex P1: original guard fired AFTER
@@ -557,9 +599,9 @@ function recallFrom(ctx, opts, windowSize, all) {
         // handle. v1.11.5 contract lock holds — api.recall does NOT write
         // last_trace_id (tests/api-recall-no-side-effects.test.ts); a trace INSERT
         // is the same observability class as the audit row it sits beside, not
-        // retrieval state. F2 fix: suppressed when the caller (currently only the
-        // MCP handler) traces its own, different result set — see
-        // opts.suppressRecallTrace JSDoc. Fail-soft internally; never throws.
+        // retrieval state. F2 fix: suppressed when the caller traces its own,
+        // different result set (retrieve under showRanked traces the shown list as
+        // 'mcp'). Fail-soft internally; never throws.
         if (!opts.suppressRecallTrace) {
             writeRecallTrace(db, {
                 tenantId: ctx.tenantId,
@@ -649,7 +691,7 @@ function recallFrom(ctx, opts, windowSize, all) {
     // detect call returns null and api.recall's anchoringHint stays absent.
     let anchoringHint = null;
     let suppressedByInterferenceCount = 0;
-    if (process.env.HIPPO_ANCHORING !== 'off' && opts.recallHistory) {
+    if (biasHintEnabled('anchoring') && opts.recallHistory) {
         const queryHash = hashQueryText(opts.query);
         const topMemoryId = rankedOut[0]?.id ?? null;
         anchoringHint = detectAnchoring(opts.recallHistory, queryHash, topMemoryId);
@@ -702,7 +744,7 @@ function recallFrom(ctx, opts, windowSize, all) {
     // opts.recallHistory gate above so we never double-emit the audit op. Audit
     // emission is pipeline-local, mirroring the J1 block above.
     let availabilityHint = null;
-    if (process.env.HIPPO_AVAILABILITY !== 'off' && !opts.suppressAvailabilityHint) {
+    if (biasHintEnabled('availability') && !opts.suppressAvailabilityHint) {
         availabilityHint = detectAvailabilityBias({
             topK: baseSlice.map((e) => ({ id: e.id, created: e.created })),
             pool: entries.map((e) => ({ id: e.id, created: e.created })),
@@ -1544,6 +1586,8 @@ export async function getContext(ctx, opts = {}) {
     const limit = opts.limit ?? Number.POSITIVE_INFINITY;
     const includeRecent = opts.includeRecent ?? 0;
     const activeScope = opts.scope ?? '';
+    assertScopeRequestAllowed(ctx.actor, opts.exactScope);
+    const exactScope = opts.exactScope || undefined;
     if (budget <= 0) {
         return { entries: [], tokens: 0 };
     }
@@ -1555,10 +1599,7 @@ export async function getContext(ctx, opts = {}) {
     const primaryIsGlobal = isGlobalStoreRoot(ctx.hippoRoot);
     const hasLocalTaskState = hasLocal && !primaryIsGlobal;
     // v39 memory scope isolation (docs/plans/2026-07-01-memory-scope-isolation.md).
-    // S2: envelope-filter parity with api.recall for AMBIENT context - private
-    // scopes and quarantine buckets never inject. `requested` is deliberately
-    // undefined: opts.scope is the scope-TAG boost input here, not an
-    // envelope-scope request (api.recall's exact-match semantics don't apply).
+    // S2: envelope-filter parity with api.recall; opts.scope is only the tag boost, opts.exactScope the envelope request.
     // S3: origin partition - other-project memories are excluded unless the
     // caller explicitly asks for them (crossProject) or isolation is disabled.
     const config = loadConfig(ctx.hippoRoot);
@@ -1579,6 +1620,10 @@ export async function getContext(ctx, opts = {}) {
         ? cost.entry({ entry, isGlobal, promptRecall, origin: entry.origin_project ?? null, category: classifyOriginProject(entry.origin_project, currentProjectName) })
         : estimateTokens(entry.content);
     const blockBudget = pinnedOnly && opts.budget === undefined ? config.pinnedInject.budget : budget;
+    const obs = opts.deliveryObserver;
+    obs?.facts({ projectName: currentProjectName, budgetTokens: blockBudget, promptRecall: promptRecallPending });
+    if (pinnedOnly && !config.pinnedInject.enabled)
+        obs?.disabled();
     let left = cost
         ? Math.max(0, blockBudget - cost.fixed(blockBudget, { cross: includeCrossProject, promptRecall: promptRecallPending, ambient: !pinnedOnly && config.ambient.enabled }))
         : blockBudget;
@@ -1601,9 +1646,8 @@ export async function getContext(ctx, opts = {}) {
             sessionId: opts.currentSessionId,
         })
         : null;
-    // W1: pre-existing leak; same `requested: undefined` ambientAdmitEntry
-    // already uses when it scope-filters memory rows above.
-    const activeSnapshot = rawActiveSnapshot && passesScopeFilterForRecall(rowScope(rawActiveSnapshot), undefined)
+    // W1: 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.
@@ -1617,7 +1661,7 @@ export async function getContext(ctx, opts = {}) {
                 // codex P2: admit scope 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), undefined)
+    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.
@@ -1625,11 +1669,12 @@ export async function getContext(ctx, opts = {}) {
         ? listSessionEvents(ctx.hippoRoot, ctx.tenantId, {
             session_id: rawActiveSnapshot.session_id,
             limit: 5,
-        }).filter((e) => passesScopeFilterForRecall(rowScope(e), undefined))
+        }).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 : [];
+    obs?.sections(Number(shownSnapshot !== null) + Number(shownHandoff !== null) + Number(shownEvents.length > 0), Number(activeSnapshot !== shownSnapshot) + Number(sessionHandoff !== shownHandoff) + Number(recentSessionEvents.length !== shownEvents.length));
     const transcriptHandoffSession = shownHandoff?.evidence?.derivedFrom === 'transcript' ? shownHandoff.sessionId : null;
     let digestHiddenForHandoff = false;
     const ambientAdmit = (e) => {
@@ -1638,7 +1683,7 @@ export async function getContext(ctx, opts = {}) {
             digestHiddenForHandoff = true;
             return false;
         }
-        return ambientAdmitEntry(e, currentProjectName, includeCrossProject);
+        return ambientAdmitEntry(e, currentProjectName, includeCrossProject, exactScope);
     };
     const ownSessionId = opts.currentSessionId || '';
     // Inside admit, not after the load, so the loader's window widens past a session's own items.
@@ -1647,12 +1692,14 @@ export async function getContext(ctx, opts = {}) {
         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);
+    const loadAdmit = obs ? obs.watchAdmit(admit) : admit;
+    const qualityDrop = (isGlobal) => obs && !promptRecallPending ? (e) => obs.qualityDropped(e, isGlobal) : undefined;
     // Tenant-scoped loads (v1.11.1 lesson: NEVER resolveTenantId({}) here).
     const localLoad = hasLocal
-        ? loadAmbientEntries(ctx.hippoRoot, ctx.tenantId, pinnedOnly, includeRecent, admit, recallRequest)
+        ? loadAmbientEntries(ctx.hippoRoot, ctx.tenantId, pinnedOnly, includeRecent, loadAdmit, recallRequest, qualityDrop(primaryIsGlobal))
         : { entries: [] };
     const globalLoad = hasGlobal && !primaryIsGlobal
-        ? loadAmbientEntries(globalRoot, ctx.tenantId, pinnedOnly, includeRecent, admit, recallRequest)
+        ? loadAmbientEntries(globalRoot, ctx.tenantId, pinnedOnly, includeRecent, loadAdmit, recallRequest, qualityDrop(true))
         : { entries: [] };
     let localEntries = localLoad.entries;
     let globalEntries = globalLoad.entries;
@@ -1677,7 +1724,10 @@ export async function getContext(ctx, opts = {}) {
         // Effective budget: explicit opts.budget wins over config, less what the sections took.
         const effBudget = left;
         const nowP = evalNow(); // honors HIPPO_FAKE_NOW (eval-only; see ablation.ts)
+        obs?.offer(localEntries, primaryIsGlobal);
+        obs?.offer(globalEntries, true);
         const [localPool, globalPool] = oneCopyPerMemory(localEntries, globalEntries, nowP);
+        obs?.dropMissing([...localEntries, ...globalEntries], [...localPool, ...globalPool], 'load', 'duplicate');
         const selectedIds = new Set();
         let usedP = 0;
         // Pinned entries are explicit user intent, the recent-N list an automatic
@@ -1743,8 +1793,23 @@ export async function getContext(ctx, opts = {}) {
                 // Candidates came off the ambient load's own connection (recallRequest above), not a fresh open.
                 // A candidate carrying a pin's text would inject that memory a second time.
                 const pinnedText = new Set(rankedPinned.map((r) => r.entry.content));
-                const eligible = (e) => admit(e) && !e.pinned && isContentWorthStoring(e.content) && !pinnedText.has(e.content);
-                const [localCandidates, globalCandidates] = oneCopyPerMemory((localLoad.recall ?? []).filter(eligible), (globalLoad.recall ?? []).filter(eligible), nowP);
+                const ineligibleReason = (e) => !admit(e) ? 'scope'
+                    : e.pinned ? 'pinned'
+                        : !isContentWorthStoring(e.content) ? 'quality'
+                            : pinnedText.has(e.content) ? 'duplicate'
+                                : null;
+                const eligible = (e) => {
+                    const why = ineligibleReason(e);
+                    if (why !== null && why !== 'pinned')
+                        obs?.reject(e, 'eligible', why);
+                    return why === null;
+                };
+                obs?.offer(localLoad.recall ?? [], primaryIsGlobal, 'prompt-recall');
+                obs?.offer(globalLoad.recall ?? [], true, 'prompt-recall');
+                const localEligible = (localLoad.recall ?? []).filter(eligible);
+                const globalEligible = (globalLoad.recall ?? []).filter(eligible);
+                const [localCandidates, globalCandidates] = oneCopyPerMemory(localEligible, globalEligible, nowP);
+                obs?.dropMissing([...localEligible, ...globalEligible], [...localCandidates, ...globalCandidates], 'eligible', 'duplicate');
                 const seenCandidateIds = new Set();
                 const candidateItems = [];
                 // Local wins the id collision (a global row synced into the local store).
@@ -1761,12 +1826,15 @@ export async function getContext(ctx, opts = {}) {
                     candidateItems.push({ id: e.id, tokens: contentTokens(e.content), entry: e, isGlobal: true });
                 }
                 const gated = gatePromptRecall(p, candidateItems, gate);
+                obs?.gated(p, candidateItems, gate, gated);
                 for (const g of gated) {
                     if (selectedIds.has(g.item.id))
                         continue;
                     const tokens = price(g.item.entry, g.item.isGlobal, true);
-                    if (usedP + tokens > recentBudget)
+                    if (usedP + tokens > recentBudget) {
+                        obs?.reject(g.item.entry, 'budget', 'budget', g.score, tokens);
                         continue;
+                    }
                     selectedItems.push({ entry: g.item.entry, score: g.score, tokens, isGlobal: g.item.isGlobal, promptRecall: true });
                     selectedIds.add(g.item.id);
                     usedP += tokens;
@@ -1818,8 +1886,10 @@ export async function getContext(ctx, opts = {}) {
             for (const r of recent) {
                 if (selectedIds.has(r.entry.id))
                     continue;
-                if (usedP + r.tokens > recentBudget)
+                if (usedP + r.tokens > recentBudget) {
+                    obs?.reject(r.entry, 'budget', 'budget', r.score, r.tokens);
                     continue;
+                }
                 selectedItems.push(r);
                 selectedIds.add(r.entry.id);
                 usedP += r.tokens;
@@ -1834,8 +1904,10 @@ export async function getContext(ctx, opts = {}) {
         for (const r of rankedPinned) {
             if (selectedIds.has(r.entry.id))
                 continue;
-            if (usedP + r.tokens > effBudget)
+            if (usedP + r.tokens > effBudget) {
+                obs?.reject(r.entry, 'budget', 'budget', r.score, r.tokens);
                 continue;
+            }
             selectedItems.push(r);
             selectedIds.add(r.entry.id);
             usedP += r.tokens;
@@ -1968,9 +2040,13 @@ export async function getContext(ctx, opts = {}) {
         }
     }
     if (limit < selectedItems.length) {
-        selectedItems = selectedItems.slice(0, limit);
+        const cut = selectedItems.slice(0, limit);
+        obs?.dropMissing(selectedItems.map((r) => r.entry), cut.map((r) => r.entry), 'limit', 'limit');
+        selectedItems = cut;
     }
-    selectedItems = dropHeldCopies(selectedItems, (r) => r.entry); // after the last cut, so a merged row that was cut hides nothing
+    const heldDropped = dropHeldCopies(selectedItems, (r) => r.entry); // after the last cut, so a merged row that was cut hides nothing
+    obs?.dropMissing(selectedItems.map((r) => r.entry), heldDropped.map((r) => r.entry), 'limit', 'duplicate');
+    selectedItems = heldDropped;
     totalTokens = selectedItems.reduce((sum, r) => sum + r.tokens, 0);
     // v39: annotate every returned entry with its origin and how it relates to
     // the active project, so renderers can demarcate cross-project inclusions.
@@ -1979,6 +2055,7 @@ export async function getContext(ctx, opts = {}) {
         origin: r.entry.origin_project ?? null,
         category: classifyOriginProject(r.entry.origin_project, currentProjectName),
     }));
+    obs?.selected(selectedItems);
     if (selectedItems.length === 0 &&
         !shownSnapshot &&
         !shownHandoff &&

package/dist/card-detail.d.ts

@@ -1,6 +1,6 @@
 import type { Card, CardComment, CardRun } from './card.js';
 import type { SessionHandoff } from './handoff.js';
-import { loadCardDeps } from './store.js';
+import { loadCardDeps } from './store-cards.js';
 /** A card plus everything `hippo card show` prints about it. */
 export interface CardDetail {
     card: Card;

package/dist/card-detail.js

@@ -1,4 +1,4 @@
-import { loadCard, loadCardComments, loadCardDeps, loadCardRuns, loadLatestHandoffForCard } from './store.js';
+import { loadCard, loadCardComments, loadCardDeps, loadCardRuns, loadLatestHandoffForCard } from './store-cards.js';
 /** Loads the detail behind `hippo card show` and `GET /api/cards/:id` (null when the tenant has no such card); five separate reads, so a write landing between them can show a mixed view, as `card show` always could. */
 export function loadCardDetail(hippoRoot, tenantId, id) {
     const card = loadCard(hippoRoot, tenantId, id);

package/dist/cli/shared.d.ts

@@ -0,0 +1,137 @@
+import { TaskSnapshot, SessionEvent } from '../store.js';
+import type { HandoffEvidence, SessionHandoff } from '../handoff.js';
+import { type SearchResult } from '../search.js';
+import { type HippoConfig } from '../config.js';
+import { openHippoDb } from '../db.js';
+import { type ImportReport } from '../agent-memories/report.js';
+import { type ChurnStaleResult } from '../invalidation.js';
+import { type AuditOp } from '../audit.js';
+import { type ServerInfo } from '../server-detect.js';
+import type { RecallSearchOpts } from '../recall-pipeline.js';
+export declare function parseLimitFlag(value: string | boolean | string[] | undefined): number;
+export declare function parseCountFlag(value: string | boolean | string[] | undefined): number;
+export declare function parseBudgetFlag(value: string | boolean | string[] | undefined, fallback: number): number;
+/**
+ * Emit an audit event against `hippoRoot`'s db. Opens its own short-lived
+ * connection so callers don't have to thread a db handle. Swallows all errors
+ * — audit must never crash a CLI command.
+ */
+export declare function emitCliAudit(hippoRoot: string, op: AuditOp, targetId?: string, metadata?: Record<string, unknown>): void;
+export declare function requireInit(hippoRoot: string): void;
+/** Runs detectChurnStale against every store this repo's memories can live in. */
+export declare function runChurnStaleForRepo(hippoRoot: string, dryRun: boolean): {
+    root: string;
+    result: ChurnStaleResult;
+}[];
+/**
+ * Run an HTTP-routed command if a `hippo serve` instance is detected for
+ * `hippoRoot`. Returns:
+ *   - true  if the HTTP path ran (success OR a structured server error that
+ *           was already surfaced to stdout/stderr by `httpFn`),
+ *   - false if no server was detected, or if the detected pidfile turned out
+ *           to be stale (connection refused). On stale, the pidfile is removed
+ *           if it still names that dead server (a newer one may have replaced
+ *           it) and the caller should fall back to the direct path.
+ *
+ * Stale pidfiles must self-heal, not crash.
+ * When HIPPO_REQUIRE_SERVER is set, both fallback paths throw instead of
+ * returning false, so a missing server fails loudly rather than silently
+ * degrading to direct mode.
+ */
+export declare function runViaServerIfAvailable(hippoRoot: string, httpFn: (info: ServerInfo, apiKey: string | undefined) => Promise<void>): Promise<boolean>;
+export declare function fmt(n: number, digits?: number): string;
+export declare function recallEntryText(r: SearchResult, query: string, showWhy: boolean, isGlobal: boolean): string;
+export declare function recallHeading(entries: number, tokens: number, query: string): string;
+/** One line when an agent memory import moved anything; its warnings go to stderr. */
+export declare function printAgentImport(report: ImportReport, indent?: string): void;
+/** The first hippo block in `text` and the agent whose current or shipped text it is; `owner` is undefined for an edited block. */
+export declare function hippoBlock(text: string): {
+    start: number;
+    end: number;
+    eol: string;
+    inner: string;
+    owner?: string;
+} | null;
+/** Adds hippo's two Codex hooks and says what changed; each install ends on the trust reminder, since Codex skips an untrusted hook. */
+export declare function installCodexMemoryHooks(indent: string): void;
+/**
+ * Set up a machine-level daily runner that sweeps all registered Hippo
+ * workspaces.
+ * Linux/macOS: writes to user crontab.
+ * Windows: creates a scheduled task.
+ * Skips if already installed.
+ */
+export declare function setupDailySchedule(globalRoot: string): void;
+export type CliFlags = Record<string, string | boolean | string[]>;
+export type EngineFlags = Pick<RecallSearchOpts, 'usePhysics' | 'physicsConfig' | 'mmr' | 'mmrLambda' | 'localBump'>;
+export declare function parseAsOfFlag(flags: CliFlags): string | undefined;
+/** --physics forces physics, --classic forces BM25+cosine, else physics unless the config turns it off. */
+export declare function engineFlags(flags: CliFlags, config: HippoConfig): EngineFlags;
+/**
+ * Detached worker that counts re-reads, runs sleep, then capture. Invoked via the internal
+ * `__session-end-worker` subcommand (not user-facing). Failures in one stage
+ * do not block the other.
+ */
+export declare function collectHandoffEvidence(cwd: string, testStatus: HandoffEvidence['testStatus']): HandoffEvidence;
+/** A folder without its own store never sleeps at session end, so its project's agent notes go to the global store here. */
+export declare function logSessionEndImport(logFile: string | null, transcriptPath: string | undefined): void;
+/**
+ * Best-effort log line for the snapshot-close step in
+ * `cmdSessionEndWorker`. `cmdSleep`/`cmdCapture` each tee console output to
+ * `logFile` only for their own duration (the tee is restored before this
+ * runs), so a plain `console.log` here would be silently discarded under
+ * the detached worker's `stdio: 'ignore'` — write straight to the file
+ * instead, matching capture.ts's `appendPreCompactLog` convention.
+ */
+export declare function appendSessionEndCloseLog(logFile: string | null, message: string, opts?: {
+    startFresh?: boolean;
+}): void;
+export declare function printActiveTaskSnapshot(snapshot: TaskSnapshot): void;
+export declare function printSessionEvents(events: SessionEvent[]): void;
+export declare function printHandoff(handoff: SessionHandoff): void;
+export declare function cardStringFlag(flags: Record<string, string | boolean | string[]>, key: string): string | undefined;
+export declare function hostSessionId(): string | undefined;
+/**
+ * Compaction drops the pinned blocks the per-prompt hook injected
+ * earlier, so record a `reset` for the payload's session and the next prompt
+ * injects again even if nothing changed. `requiredSource` limits it to hook
+ * payloads with that `source` (SessionStart fires for other reasons too).
+ * Best-effort and silent: a malformed payload records nothing.
+ */
+export declare function resetHookInjection(hippoRoot: string, stdinText: string | undefined, requiredSource: string | null): void;
+/**
+ * Run `fn` with console.log captured; returns the captured lines joined by
+ * newlines (what the same calls would have printed, minus the final newline).
+ */
+export declare function captureConsole(fn: () => void): string;
+/**
+ * The store a Claude Code hook writes to: the project store when there is
+ * one, else an existing global store, else the project path (which the hook
+ * then skips, since hooks fire in every directory and must not create one).
+ * Pre-compact and compact-resume must agree, or a snapshot saved to one store
+ * is looked for in the other.
+ */
+export declare function hookStoreRoot(hippoRoot: string): string;
+/**
+ * Run `fn` against the token ledger's store: the local store when it is
+ * initialized, else the global one (the per-prompt hook runs in directories
+ * without a local store). Best-effort: returns undefined and never throws,
+ * because a ledger failure must not break context or recall.
+ */
+export declare function withLedgerDb<T>(hippoRoot: string, fn: (db: ReturnType<typeof openHippoDb>) => T): T | undefined;
+export declare function learnFromRepo(hippoRoot: string, repoPath: string, days: number, label?: string): {
+    added: number;
+    skipped: number;
+    lowInfo: number;
+};
+export declare const HOOK_MARKERS: {
+    start: string;
+    end: string;
+};
+export declare const HOOKS: Record<string, {
+    file: string;
+    content: string;
+    description: string;
+}>;
+export declare function resolveAuthRoot(hippoRoot: string, flags: Record<string, string | boolean | string[]>): string;
+//# sourceMappingURL=shared.d.ts.map