hippo-memory 1.55.0 → 1.56.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,6 +17,7 @@ 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 { consolidate } from './consolidate.js';
@@ -974,6 +975,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

@@ -135,12 +135,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.
@@ -1579,6 +1586,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;
@@ -1630,6 +1641,7 @@ export async function getContext(ctx, opts = {}) {
     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) => {
@@ -1647,12 +1659,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 +1691,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 +1760,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 +1793,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 +1853,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 +1871,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 +2007,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 +2022,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/cli.js

@@ -51,7 +51,8 @@ import { passesScopeFilterForRecall } from './recall-scope.js';
 import { estimateTokens, fitBudget, hybridSearch, physicsSearch, explainMatch, textOverlap, tokenize as tokenizeQuery } from './search.js';
 import { compareEntryIdentity } from './compare.js';
 import { renderTraceContent, parseSteps } from './trace.js';
-import { writeRecallTraceAtRoot } from './recall-trace.js';
+import { writeDeliveryEventAtRoot, writeDeliveryEventOnHandle, writeRecallTraceAtRoot } from './recall-trace.js';
+import { createDeliveryRecorder } from './delivery-recorder.js';
 import { deduplicateStore } from './dedupe.js';
 import { isEmbeddingAvailable, embedAll, embedMemory, loadEmbeddingIndex, resolveEmbeddingModel, embeddingModelRequiresReindex, } from './embeddings.js';
 import { resolveEmbeddingProvider } from './embedding-provider.js';
@@ -6291,6 +6292,46 @@ function hostSessionId() {
     return process.env.HIPPO_SESSION_ID?.trim() || process.env.CLAUDE_CODE_SESSION_ID?.trim() || undefined;
 }
 async function cmdContext(hippoRoot, args, flags, stdinText) {
+    const rec = startDeliveryRecorder(hippoRoot, flags, stdinText);
+    // No try/finally: a render throw keeps its own exit code and writes no event.
+    await renderContext(hippoRoot, args, flags, stdinText, rec);
+    flushDeliveryRecorder(rec);
+}
+/** A delivery recorder for a pinned-only call when its ledger store enables one, else null; never throws. */
+function startDeliveryRecorder(hippoRoot, flags, stdinText) {
+    if (flags['pinned-only'] !== true)
+        return null;
+    try {
+        // The same store withLedgerDb writes the token ledger to, so its config governs both.
+        const root = isInitialized(hippoRoot) ? hippoRoot : isInitialized(getGlobalRoot()) ? getGlobalRoot() : null;
+        if (root === null || !loadConfig(root).deliveryLedger.enabled)
+            return null;
+        return createDeliveryRecorder({
+            root,
+            storeHash: blockHash(path.resolve(root)),
+            writeStore: isGlobalStoreRoot(root) ? 'global' : 'local',
+            tenantId: resolveTenantId({}),
+            stdinText,
+            envSessionId: hostSessionId(),
+        });
+    }
+    catch (error) {
+        console.error(`[hippo] delivery ledger skipped: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+/** With `db`, writes on the token ledger's handle (same store); without it, opens its own. A second flush is a no-op. */
+function flushDeliveryRecorder(rec, db) {
+    if (rec === null)
+        return;
+    try {
+        rec.flush((input) => (db ? writeDeliveryEventOnHandle(db, input) : writeDeliveryEventAtRoot(rec.root, input)));
+    }
+    catch (error) {
+        console.error(`[hippo] delivery ledger write failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+async function renderContext(hippoRoot, args, flags, stdinText, rec) {
     // --pinned-only fires on every UserPromptSubmit — including in directories
     // that don't have a local .hippo. Skip requireInit for that path and fall
     // back to global-only inside api.getContext. The non-pinned path still
@@ -6300,8 +6341,10 @@ async function cmdContext(hippoRoot, args, flags, stdinText) {
         requireInit(hippoRoot);
     }
     const budget = parseBudgetFlag(flags['budget'], 1500);
-    if (budget <= 0)
+    if (budget <= 0) {
+        rec?.disabled();
         return;
+    }
     // Resolve query: explicit args, --auto (git diff via CLI-side helper), or
     // fall through to api.getContext's '*' fallback. api.getContext is host-
     // agnostic so the auto-detect (which shells out to git) stays CLI-side.
@@ -6362,6 +6405,7 @@ async function cmdContext(hippoRoot, args, flags, stdinText) {
         prompt: payloadPrompt,
         // JSON is budgeted as the markdown it stands for, so one budget picks the same memories in every format.
         cost: contextCost(format === 'additional-context' ? 'additional-context' : 'markdown', framing),
+        deliveryObserver: rec ?? undefined,
     };
     const result = await api.getContext(ctx, opts);
     // Early exit when there's nothing to render (matches pre-extraction behavior).
@@ -6369,8 +6413,10 @@ async function cmdContext(hippoRoot, args, flags, stdinText) {
         result.activeSnapshot ||
         result.sessionHandoff ||
         (result.recentEvents && result.recentEvents.length > 0);
-    if (!hasContextData)
+    if (!hasContextData) {
+        rec?.delivered({ state: 'empty' });
         return;
+    }
     // Adapter: ContextResultEntry -> the print-helper input shape. v39:
     // cross-project inclusions (only present under --cross-project or with
     // isolation disabled via crossProject) render in their own demarcated
@@ -6404,10 +6450,14 @@ async function cmdContext(hippoRoot, args, flags, stdinText) {
             tokens: result.tokens,
         });
         console.log(jsonText);
-        withLedgerDb(hippoRoot, (db) => recordTokenUse(db, {
-            tenantId: ctx.tenantId, sessionId: ledgerSessionId, surface: pinnedOnly ? 'hook' : 'context',
-            event: 'inject', items: output.length, tokens: estimateTokens(jsonText),
-        }));
+        rec?.delivered({ state: 'sent', emittedText: `${jsonText}\n` });
+        withLedgerDb(hippoRoot, (db) => {
+            recordTokenUse(db, {
+                tenantId: ctx.tenantId, sessionId: ledgerSessionId, surface: pinnedOnly ? 'hook' : 'context',
+                event: 'inject', items: output.length, tokens: estimateTokens(jsonText),
+            });
+            flushDeliveryRecorder(rec, db);
+        });
     }
     else if (format === 'additional-context') {
         // Z1: split into a static block (snapshot/handoff/events/pins/recent-N,
@@ -6433,8 +6483,10 @@ async function cmdContext(hippoRoot, args, flags, stdinText) {
         const recallBlock = recallItems.length > 0
             ? settleTokens((t) => captureConsole(() => printContextMarkdown(recallItems, t, framing, { showStrength: false, heading: 'Prompt-Relevant Memory' })))
             : '';
-        if (!staticBlock.trim() && !recallBlock.trim())
+        if (!staticBlock.trim() && !recallBlock.trim()) {
+            rec?.delivered({ state: 'empty' });
             return;
+        }
         const surface = pinnedOnly ? 'hook' : 'context';
         let sendStatic = staticBlock.trim().length > 0;
         // TE2: the per-prompt hook skips a static block identical to the one this
@@ -6449,10 +6501,16 @@ async function cmdContext(hippoRoot, args, flags, stdinText) {
                 const staticHash = blockHash(staticBlock);
                 const last = withLedgerDb(hippoRoot, (db) => lastSentState(db, ctx.tenantId, payloadSessionId, surface));
                 if (shouldSkipUnchanged(last ?? null, staticHash, refreshTurns)) {
-                    withLedgerDb(hippoRoot, (db) => recordTokenUse(db, {
-                        tenantId: ctx.tenantId, sessionId: payloadSessionId, surface, event: 'skip',
-                        items: staticItems.length, tokens: estimateTokens(staticBlock), hash: staticHash,
-                    }));
+                    withLedgerDb(hippoRoot, (db) => {
+                        recordTokenUse(db, {
+                            tenantId: ctx.tenantId, sessionId: payloadSessionId, surface, event: 'skip',
+                            items: staticItems.length, tokens: estimateTokens(staticBlock), hash: staticHash,
+                        });
+                        if (recallBlock.trim())
+                            return;
+                        rec?.delivered({ state: 'reused', staticHash, staticReused: true });
+                        flushDeliveryRecorder(rec, db);
+                    });
                     sendStatic = false;
                 }
             }
@@ -6461,8 +6519,11 @@ async function cmdContext(hippoRoot, args, flags, stdinText) {
         const additionalContext = finalStatic && recallBlock
             ? `${finalStatic}\n\n${recallBlock}`
             : finalStatic || recallBlock;
-        if (!additionalContext.trim())
+        const staticReused = !sendStatic && staticBlock.trim().length > 0;
+        if (!additionalContext.trim()) {
+            rec?.delivered({ state: 'reused', staticHash: blockHash(staticBlock), staticReused });
             return;
+        }
         const payload = {
             hookSpecificOutput: {
                 hookEventName: 'UserPromptSubmit',
@@ -6470,6 +6531,13 @@ async function cmdContext(hippoRoot, args, flags, stdinText) {
             },
         };
         process.stdout.write(JSON.stringify(payload));
+        rec?.delivered({
+            state: staticReused ? 'reused-recall-sent' : 'sent',
+            staticHash: staticBlock.trim() ? blockHash(staticBlock) : null,
+            recallHash: recallBlock ? blockHash(recallBlock) : null,
+            emittedText: additionalContext,
+            staticReused,
+        });
         if (finalStatic || recallBlock) {
             // One connection for both rows; each insert in its own try so one failing doesn't skip the other.
             withLedgerDb(hippoRoot, (db) => {
@@ -6491,6 +6559,7 @@ async function cmdContext(hippoRoot, args, flags, stdinText) {
                     }
                     catch { /* best effort; see withLedgerDb doc comment */ }
                 }
+                flushDeliveryRecorder(rec, db);
             });
         }
     }
@@ -6515,10 +6584,14 @@ async function cmdContext(hippoRoot, args, flags, stdinText) {
         }));
         if (text.length > 0)
             console.log(text);
-        withLedgerDb(hippoRoot, (db) => recordTokenUse(db, {
-            tenantId: ctx.tenantId, sessionId: ledgerSessionId, surface: pinnedOnly ? 'hook' : 'context',
-            event: 'inject', items: renderItems.length, tokens: estimateTokens(text),
-        }));
+        rec?.delivered(text.length > 0 ? { state: 'sent', emittedText: `${text}\n` } : { state: 'empty' });
+        withLedgerDb(hippoRoot, (db) => {
+            recordTokenUse(db, {
+                tenantId: ctx.tenantId, sessionId: ledgerSessionId, surface: pinnedOnly ? 'hook' : 'context',
+                event: 'inject', items: renderItems.length, tokens: estimateTokens(text),
+            });
+            flushDeliveryRecorder(rec, db);
+        });
     }
 }
 /**

package/dist/config.d.ts

@@ -140,6 +140,11 @@ export interface HippoConfig {
     agentMemories: {
         tools: string[] | null;
     };
+    /** Per-turn delivery ledger (src/recall-trace.ts): hashes, ids, counts and rejection reasons for each
+     *  pinned-only context call. Default off; read from the store the token ledger writes to. */
+    deliveryLedger: {
+        enabled: boolean;
+    };
 }
 export declare function loadConfig(hippoRoot: string): HippoConfig;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -85,6 +85,9 @@ const DEFAULT_CONFIG = {
     agentMemories: {
         tools: null,
     },
+    deliveryLedger: {
+        enabled: false,
+    },
 };
 function isMemoryValueConfig(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -95,6 +98,23 @@ function isDormantConfig(value) {
 function isChurnStalenessConfig(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+function isDeliveryLedgerConfig(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// Only `{"enabled": true}` turns it on; anything malformed warns and stays off.
+function deliveryLedgerEnabled(value) {
+    if (value === undefined)
+        return false;
+    const isObject = isDeliveryLedgerConfig(value);
+    const enabled = isObject ? value.enabled : undefined;
+    if (enabled === true || enabled === false)
+        return enabled;
+    if (isObject && enabled === undefined)
+        return false;
+    console.error(`Warning: config.json's "deliveryLedger" must be an object like {"enabled": true} ` +
+        `(got ${JSON.stringify(value)}) - using false.`);
+    return false;
+}
 function agentMemoryTools(value) {
     if (value === undefined || value === null)
         return null;
@@ -205,6 +225,7 @@ export function loadConfig(hippoRoot) {
                 enabled: churnStalenessEnabled,
             },
             agentMemories: { tools: agentMemoryTools(raw.agentMemories?.tools) },
+            deliveryLedger: { enabled: deliveryLedgerEnabled(raw.deliveryLedger) },
         };
     }
     catch (err) {

package/dist/db.js

@@ -11,7 +11,7 @@ const require = createRequire(import.meta.url);
 // runtime (Node's built-in synchronous SQLite module); there are no bundled
 // types for it here, so this require + cast is the module's documented boundary.
 const { DatabaseSync } = require('node:sqlite');
-const CURRENT_SCHEMA_VERSION = 49;
+const CURRENT_SCHEMA_VERSION = 50;
 const MIGRATIONS = [
     {
         version: 1,
@@ -2501,6 +2501,72 @@ const MIGRATIONS = [
       `);
         },
     },
+    {
+        version: 50,
+        up: (db) => {
+            // Per-turn delivery events (src/recall-trace.ts). Additive only: no min_compatible_binary bump; rollback drops both tables
+            // and sets schema_version back to 49. No CHECK on enum columns since SQLite cannot alter one; delivery-recorder.ts unions are the allowlist.
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS delivery_events (
+          id                INTEGER PRIMARY KEY AUTOINCREMENT,
+          ts                TEXT NOT NULL,
+          ledger_version    INTEGER NOT NULL,
+          tenant_id         TEXT NOT NULL DEFAULT 'default',
+          runtime           TEXT NOT NULL,
+          event_type        TEXT NOT NULL,
+          surface           TEXT NOT NULL,
+          store_hash        TEXT NOT NULL,
+          write_store       TEXT NOT NULL,
+          project_hash      TEXT,
+          session_id        TEXT,
+          session_state     TEXT NOT NULL,
+          host_turn_id      TEXT,
+          turn_seq          INTEGER,
+          duplicate_of      INTEGER,
+          prompt_hash       TEXT,
+          prompt_length     INTEGER NOT NULL DEFAULT 0,
+          query_hash        TEXT,
+          recall_trace_id   INTEGER,
+          block_state       TEXT NOT NULL,
+          prompt_recall     INTEGER NOT NULL DEFAULT 0,
+          considered_count  INTEGER NOT NULL DEFAULT 0,
+          filtered_count    INTEGER NOT NULL DEFAULT 0,
+          selected_count    INTEGER NOT NULL DEFAULT 0,
+          emitted_count     INTEGER NOT NULL DEFAULT 0,
+          rejected_count    INTEGER NOT NULL DEFAULT 0,
+          rejected_unlisted INTEGER NOT NULL DEFAULT 0,
+          sections_shown    INTEGER NOT NULL DEFAULT 0,
+          sections_dropped  INTEGER NOT NULL DEFAULT 0,
+          budget_tokens     INTEGER NOT NULL DEFAULT 0,
+          selected_tokens   INTEGER NOT NULL DEFAULT 0,
+          injected_tokens   INTEGER NOT NULL DEFAULT 0,
+          static_hash       TEXT,
+          recall_hash       TEXT,
+          emitted_hash      TEXT,
+          elapsed_ms        INTEGER NOT NULL DEFAULT 0
+        );
+        CREATE INDEX IF NOT EXISTS idx_delivery_events_session ON delivery_events(tenant_id, session_id, id);
+        CREATE INDEX IF NOT EXISTS idx_delivery_events_ts ON delivery_events(ts);
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_delivery_events_turn
+          ON delivery_events(tenant_id, session_id, event_type, turn_seq) WHERE turn_seq IS NOT NULL;
+
+        CREATE TABLE IF NOT EXISTS delivery_candidates (
+          event_id     INTEGER NOT NULL REFERENCES delivery_events(id) ON DELETE CASCADE,
+          tenant_id    TEXT NOT NULL DEFAULT 'default',
+          memory_id    TEXT NOT NULL,          -- no FK: events outlive forgotten memories, as recall traces do
+          source_store TEXT NOT NULL,
+          pool         TEXT NOT NULL,
+          stage        TEXT NOT NULL,
+          outcome      TEXT NOT NULL,
+          reason       TEXT,
+          cand_rank    INTEGER,
+          score        REAL,
+          tokens       INTEGER,
+          PRIMARY KEY (event_id, memory_id)
+        ) WITHOUT ROWID;
+      `);
+        },
+    },
 ];
 function tableHasColumn(db, tableName, columnName) {
     if (!/^[a-z_]+$/i.test(tableName))

package/dist/delivery-recorder.d.ts

@@ -0,0 +1,127 @@
+import type { MemoryEntry } from './memory.js';
+import { type PromptRecallGate } from './prompt-recall.js';
+export type DeliveryRuntime = 'claude-code' | 'codex' | 'unknown';
+export type DeliveryEventType = 'prompt-submit' | 'pinned-manual';
+export type DeliverySurface = 'hook' | 'context';
+export type DeliveryWriteStore = 'local' | 'global';
+export type DeliverySessionState = 'payload' | 'env' | 'missing' | 'subagent';
+export type DeliveryBlockState = 'sent' | 'reused' | 'reused-recall-sent' | 'empty' | 'disabled';
+export type DeliveryPool = 'pin' | 'recent' | 'prompt-recall' | 'strength' | 'search';
+export type DeliveryStage = 'load' | 'eligible' | 'gate' | 'budget' | 'limit' | 'final';
+export type DeliveryOutcome = 'emitted' | 'reused' | 'rejected';
+export type DeliveryRejectReason = 'budget' | 'gate-below-threshold' | 'gate-max-items' | 'duplicate' | 'scope' | 'quality' | 'limit';
+/** Row format version written to `delivery_events.ledger_version`. */
+export declare const DELIVERY_LEDGER_VERSION = 1;
+/** Rejected candidate rows kept per event; the rest only add to `rejected_unlisted`. */
+export declare const DELIVERY_REJECTED_ROW_CAP = 16;
+export interface DeliveryCandidateInput {
+    memoryId: string;
+    sourceStore: DeliveryWriteStore;
+    pool: DeliveryPool;
+    stage: DeliveryStage;
+    outcome: DeliveryOutcome;
+    reason: DeliveryRejectReason | null;
+    rank: number | null;
+    score: number | null;
+    tokens: number | null;
+}
+/** One event as the writer stores it; the writer adds `turn_seq`, `duplicate_of` and the format version. */
+export interface DeliveryEventInput {
+    ts: string;
+    tenantId: string;
+    runtime: DeliveryRuntime;
+    eventType: DeliveryEventType;
+    surface: DeliverySurface;
+    storeHash: string;
+    writeStore: DeliveryWriteStore;
+    projectHash: string | null;
+    sessionId: string | null;
+    sessionState: DeliverySessionState;
+    hostTurnId: string | null;
+    promptHash: string | null;
+    promptLength: number;
+    queryHash: string | null;
+    recallTraceId: number | null;
+    blockState: DeliveryBlockState;
+    promptRecall: boolean;
+    consideredCount: number;
+    filteredCount: number;
+    selectedCount: number;
+    emittedCount: number;
+    rejectedCount: number;
+    rejectedUnlisted: number;
+    sectionsShown: number;
+    sectionsDropped: number;
+    budgetTokens: number;
+    selectedTokens: number;
+    injectedTokens: number;
+    staticHash: string | null;
+    recallHash: string | null;
+    emittedHash: string | null;
+    elapsedMs: number;
+    candidates: readonly DeliveryCandidateInput[];
+}
+export interface DeliveryFacts {
+    projectName: string;
+    budgetTokens: number;
+    promptRecall: boolean;
+}
+/** The shape of a returned context entry the observer reads. */
+export interface DeliverySelected {
+    entry: MemoryEntry;
+    score: number;
+    tokens: number;
+    isGlobal?: boolean;
+    promptRecall?: boolean;
+}
+/** What getContext reports while it selects. Every method only reads; none changes what is selected. */
+export interface DeliveryObserver {
+    facts(facts: DeliveryFacts): void;
+    sections(shown: number, dropped: number): void;
+    /** Returns `admit`'s own answer unchanged and lets its throws through. */
+    watchAdmit(admit: (e: MemoryEntry) => boolean): (e: MemoryEntry) => boolean;
+    /** The loader's quality floor dropped a row admit let through; with prompt recall on, eligibility reports it instead. */
+    qualityDropped(entry: MemoryEntry, isGlobal: boolean): void;
+    disabled(): void;
+    /** No `pool` means pin or recent by the entry's own flag. */
+    offer(entries: readonly MemoryEntry[], isGlobal: boolean, pool?: DeliveryPool): void;
+    reject(entry: MemoryEntry, stage: DeliveryStage, reason: DeliveryRejectReason, score?: number, tokens?: number): void;
+    dropMissing(before: readonly MemoryEntry[], after: readonly MemoryEntry[], stage: DeliveryStage, reason: DeliveryRejectReason): void;
+    gated(prompt: ReadonlySet<string>, candidates: readonly {
+        id: string;
+        tokens: ReadonlySet<string>;
+    }[], gate: PromptRecallGate, kept: readonly {
+        item: {
+            id: string;
+        };
+    }[]): void;
+    selected(items: readonly DeliverySelected[]): void;
+}
+/** What the renderer sent, reported once at its exit. */
+export interface DeliveryOutcomeInput {
+    state: DeliveryBlockState;
+    staticHash?: string | null;
+    recallHash?: string | null;
+    /** The exact text the agent receives: the hook's additionalContext, or every stdout byte, newline included. */
+    emittedText?: string | null;
+    /** The static block was skipped as unchanged, so its entries are reused, not sent. */
+    staticReused?: boolean;
+}
+export interface DeliveryRecorder extends DeliveryObserver {
+    readonly root: string;
+    delivered(outcome: DeliveryOutcomeInput): void;
+    /** Builds the event and hands it to `write` once per call; throws on an injected fault, and writes nothing once broken. */
+    flush(write: (input: DeliveryEventInput) => number | null): void;
+}
+export interface DeliveryRecorderInit {
+    /** The store the event is written to. */
+    root: string;
+    storeHash: string;
+    writeStore: DeliveryWriteStore;
+    tenantId: string;
+    stdinText?: string;
+    envSessionId?: string;
+}
+/** A recorder for one call; every observer method is guarded, and a throw marks it broken instead of escaping. */
+export declare function createDeliveryRecorder(init: DeliveryRecorderInit): DeliveryRecorder;
+//# sourceMappingURL=delivery-recorder.d.ts.map

package/dist/delivery-recorder.js

@@ -0,0 +1,218 @@
+import { evalNow } from './ablation.js';
+import { scoreOverlap } from './prompt-recall.js';
+import { blockHash, estimateTokens, hookPayloadSessionId, hookPayloadString, isSubagentPayload } from './token-ledger.js';
+/** Row format version written to `delivery_events.ledger_version`. */
+export const DELIVERY_LEDGER_VERSION = 1;
+/** Rejected candidate rows kept per event; the rest only add to `rejected_unlisted`. */
+export const DELIVERY_REJECTED_ROW_CAP = 16;
+// Deeper stages were closer to being sent, so the row cap keeps them first.
+const STAGE_DEPTH = new Map([
+    ['load', 0], ['eligible', 1], ['gate', 2], ['budget', 3], ['limit', 4], ['final', 5],
+]);
+function storeOf(isGlobal) {
+    return isGlobal === true ? 'global' : 'local';
+}
+function byDepthThenScore(a, b) {
+    const depth = (STAGE_DEPTH.get(b.stage ?? 'load') ?? 0) - (STAGE_DEPTH.get(a.stage ?? 'load') ?? 0);
+    if (depth !== 0)
+        return depth;
+    const score = (b.score ?? Number.NEGATIVE_INFINITY) - (a.score ?? Number.NEGATIVE_INFINITY);
+    if (score !== 0 && !Number.isNaN(score))
+        return score;
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+/** A recorder for one call; every observer method is guarded, and a throw marks it broken instead of escaping. */
+export function createDeliveryRecorder(init) {
+    const startedMs = Date.now();
+    const ts = evalNow().toISOString();
+    // Test-only fault injection, as HIPPO_FAKE_NOW is for time.
+    const fault = process.env.HIPPO_TEST_DELIVERY_FAULT ?? '';
+    const payloadSession = hookPayloadSessionId(init.stdinText);
+    const subagent = isSubagentPayload(init.stdinText);
+    const envSession = init.envSessionId !== undefined && init.envSessionId !== '' ? init.envSessionId : null;
+    const prompt = hookPayloadString(init.stdinText, 'prompt');
+    const rawTurnId = hookPayloadString(init.stdinText, 'turn_id');
+    const hostTurnId = rawTurnId !== null && rawTurnId.trim() !== '' ? rawTurnId : null;
+    const hookEvent = hookPayloadString(init.stdinText, 'hook_event_name');
+    const sessionState = subagent
+        ? 'subagent'
+        : payloadSession !== null ? 'payload' : envSession !== null ? 'env' : 'missing';
+    const candidates = new Map();
+    const picked = new Map();
+    const filtered = new Set();
+    let facts = null;
+    let shown = 0;
+    let dropped = 0;
+    let disabledSeen = false;
+    let outcome = { state: 'empty' };
+    let broken = null;
+    let flushed = false;
+    const guard = (fn) => {
+        if (broken !== null)
+            return;
+        try {
+            if (fault === 'observe')
+                throw new Error('injected observe fault');
+            fn();
+        }
+        catch (error) {
+            broken = error instanceof Error ? error.message : String(error);
+        }
+    };
+    const rejectId = (id, stage, reason, score, tokens) => {
+        const held = candidates.get(id);
+        // First rejection wins; an id never offered is not a candidate of this call.
+        if (!held || held.reason !== null)
+            return;
+        candidates.set(id, { ...held, stage, reason, score, tokens });
+    };
+    const build = () => {
+        if (fault === 'build')
+            throw new Error('injected build fault');
+        const staticReused = outcome.staticReused === true;
+        const rows = [];
+        for (const p of picked.values()) {
+            const held = candidates.get(p.entry.id);
+            rows.push({
+                memoryId: p.entry.id,
+                sourceStore: p.sourceStore,
+                pool: p.promptRecall ? 'prompt-recall' : held?.pool === 'pin' || p.entry.pinned ? 'pin' : 'recent',
+                stage: 'final',
+                outcome: staticReused && !p.promptRecall ? 'reused' : 'emitted',
+                reason: null,
+                rank: p.rank,
+                score: p.score,
+                tokens: p.tokens,
+            });
+        }
+        const rejected = [];
+        let undecided = 0;
+        for (const c of candidates.values()) {
+            if (picked.has(c.id))
+                continue;
+            if (c.reason === null)
+                undecided += 1;
+            else
+                rejected.push(c);
+        }
+        rejected.sort(byDepthThenScore);
+        for (const c of rejected.slice(0, DELIVERY_REJECTED_ROW_CAP)) {
+            rows.push({
+                memoryId: c.id, sourceStore: c.sourceStore, pool: c.pool, stage: c.stage ?? 'load', outcome: 'rejected',
+                reason: c.reason, rank: null, score: c.score, tokens: c.tokens,
+            });
+        }
+        const overflow = Math.max(0, rejected.length - DELIVERY_REJECTED_ROW_CAP);
+        const emitted = outcome.emittedText ?? null;
+        return {
+            ts,
+            tenantId: init.tenantId,
+            runtime: hostTurnId !== null ? 'codex' : hookEvent !== null ? 'claude-code' : 'unknown',
+            eventType: hookEvent === 'UserPromptSubmit' ? 'prompt-submit' : 'pinned-manual',
+            surface: 'hook',
+            storeHash: init.storeHash,
+            writeStore: init.writeStore,
+            projectHash: facts !== null && facts.projectName !== '' ? blockHash(facts.projectName) : null,
+            sessionId: payloadSession ?? envSession,
+            sessionState,
+            hostTurnId,
+            promptHash: prompt !== null ? blockHash(prompt) : null,
+            promptLength: prompt?.length ?? 0,
+            queryHash: null,
+            recallTraceId: null,
+            blockState: disabledSeen ? 'disabled' : outcome.state,
+            promptRecall: facts?.promptRecall === true,
+            consideredCount: new Set([...candidates.keys(), ...picked.keys()]).size,
+            filteredCount: filtered.size,
+            selectedCount: picked.size,
+            emittedCount: rows.filter((r) => r.outcome === 'emitted').length,
+            rejectedCount: rejected.length + undecided,
+            rejectedUnlisted: overflow + undecided,
+            sectionsShown: shown,
+            sectionsDropped: dropped,
+            budgetTokens: facts?.budgetTokens ?? 0,
+            selectedTokens: [...picked.values()].reduce((sum, p) => sum + p.tokens, 0),
+            injectedTokens: emitted !== null ? estimateTokens(emitted) : 0,
+            staticHash: outcome.staticHash ?? null,
+            recallHash: outcome.recallHash ?? null,
+            emittedHash: emitted !== null ? blockHash(emitted) : null,
+            elapsedMs: Math.max(0, Date.now() - startedMs),
+            candidates: rows,
+        };
+    };
+    return {
+        root: init.root,
+        facts: (f) => guard(() => { facts = { ...f }; }),
+        sections: (s, d) => guard(() => { shown = s; dropped = d; }),
+        watchAdmit: (admit) => (e) => {
+            const ok = admit(e);
+            if (!ok)
+                guard(() => { filtered.add(e.id); });
+            return ok;
+        },
+        qualityDropped: (e, isGlobal) => guard(() => {
+            filtered.add(e.id);
+            if (!candidates.has(e.id)) {
+                candidates.set(e.id, {
+                    id: e.id, sourceStore: storeOf(isGlobal), pool: 'recent', stage: null, reason: null, score: null, tokens: null,
+                });
+            }
+            rejectId(e.id, 'load', 'quality', null, null);
+        }),
+        disabled: () => guard(() => { disabledSeen = true; }),
+        offer: (entries, isGlobal, pool) => guard(() => {
+            for (const e of entries) {
+                const held = candidates.get(e.id);
+                const wanted = pool ?? (e.pinned ? 'pin' : 'recent');
+                // A loaded recent row the prompt-recall gate then judges belongs to that pool.
+                const relabel = held !== undefined && held.reason === null && held.pool === 'recent' && wanted === 'prompt-recall';
+                if (held !== undefined && !relabel)
+                    continue;
+                candidates.set(e.id, {
+                    id: e.id, sourceStore: storeOf(isGlobal), pool: wanted, stage: null, reason: null, score: null, tokens: null,
+                });
+            }
+        }),
+        reject: (e, stage, reason, score, tokens) => guard(() => rejectId(e.id, stage, reason, score ?? null, tokens ?? null)),
+        dropMissing: (before, after, stage, reason) => guard(() => {
+            const kept = new Set(after.map((e) => e.id));
+            for (const e of before)
+                if (!kept.has(e.id))
+                    rejectId(e.id, stage, reason, null, null);
+        }),
+        gated: (prompt, items, gate, kept) => guard(() => {
+            const keptIds = new Set(kept.map((g) => g.item.id));
+            for (const c of items) {
+                if (keptIds.has(c.id))
+                    continue;
+                const { score, shared } = scoreOverlap(prompt, c.tokens, gate.metric);
+                const cleared = score >= gate.threshold && shared >= gate.minShared;
+                rejectId(c.id, 'gate', cleared ? 'gate-max-items' : 'gate-below-threshold', score, null);
+            }
+        }),
+        selected: (items) => guard(() => {
+            picked.clear();
+            items.forEach((r, i) => {
+                picked.set(r.entry.id, {
+                    entry: r.entry, rank: i + 1, score: r.score, tokens: r.tokens,
+                    sourceStore: storeOf(r.isGlobal), promptRecall: r.promptRecall === true,
+                });
+            });
+        }),
+        delivered: (o) => guard(() => { outcome = { ...o }; }),
+        flush: (write) => {
+            if (flushed)
+                return;
+            flushed = true;
+            if (broken !== null) {
+                console.error(`[hippo] delivery ledger skipped: recorder failed: ${broken}`);
+                return;
+            }
+            const input = build();
+            if (fault === 'flush')
+                throw new Error('injected flush fault');
+            write(input);
+        },
+    };
+}
+//# sourceMappingURL=delivery-recorder.js.map

package/dist/recall-trace.d.ts

@@ -17,6 +17,7 @@
  */
 import { type DatabaseSyncLike } from './db.js';
 import type { RerankStep } from './search.js';
+import { type DeliveryEventInput } from './delivery-recorder.js';
 /** One ranked result to persist alongside its trace row. */
 export interface RecallTraceResultInput {
     memoryId: string;
@@ -114,4 +115,72 @@ export interface RecordTraceOutcomeInput {
  * Fail-soft: never throws.
  */
 export declare function recordTraceOutcome(db: DatabaseSyncLike, input: RecordTraceOutcomeInput): void;
+/** Pruned on write, counted back from the event's ts capped at the real clock, so a far-future fake time spares real rows. */
+export declare const DELIVERY_LEDGER_RETENTION_DAYS = 90;
+/** Lock wait for the ledger's own connection: a busy store drops the row rather than slow the hook. */
+export declare const DELIVERY_LEDGER_WAIT_MS = 50;
+/** Two prompt-identical events without a host turn id this close together are one turn fired twice. */
+export declare const DELIVERY_DUPLICATE_WINDOW_MS = 2000;
+/** One stored `delivery_candidates` row. */
+export interface DeliveryCandidateRow {
+    event_id: number;
+    tenant_id: string;
+    memory_id: string;
+    source_store: string;
+    pool: string;
+    stage: string;
+    outcome: string;
+    reason: string | null;
+    cand_rank: number | null;
+    score: number | null;
+    tokens: number | null;
+}
+/** One stored `delivery_events` row with its candidate rows. */
+export interface DeliveryEventRow {
+    id: number;
+    ts: string;
+    ledger_version: number;
+    tenant_id: string;
+    runtime: string;
+    event_type: string;
+    surface: string;
+    store_hash: string;
+    write_store: string;
+    project_hash: string | null;
+    session_id: string | null;
+    session_state: string;
+    host_turn_id: string | null;
+    turn_seq: number | null;
+    duplicate_of: number | null;
+    prompt_hash: string | null;
+    prompt_length: number;
+    query_hash: string | null;
+    recall_trace_id: number | null;
+    block_state: string;
+    prompt_recall: number;
+    considered_count: number;
+    filtered_count: number;
+    selected_count: number;
+    emitted_count: number;
+    rejected_count: number;
+    rejected_unlisted: number;
+    sections_shown: number;
+    sections_dropped: number;
+    budget_tokens: number;
+    selected_tokens: number;
+    injected_tokens: number;
+    static_hash: string | null;
+    recall_hash: string | null;
+    emitted_hash: string | null;
+    elapsed_ms: number;
+    candidates: DeliveryCandidateRow[];
+}
+/** One event plus its candidates in one write transaction, then prune; fail-soft. The caller must not hold a transaction on `db`. */
+export declare function writeDeliveryEvent(db: DatabaseSyncLike, input: DeliveryEventInput): number | null;
+/** Write on a short-lived connection that waits at most {@link DELIVERY_LEDGER_WAIT_MS} for the lock. Fail-soft. */
+export declare function writeDeliveryEventAtRoot(root: string, input: DeliveryEventInput): number | null;
+/** On a caller's open handle, which saves a second open and close per turn; the handle's own lock wait comes back after. */
+export declare function writeDeliveryEventOnHandle(db: DatabaseSyncLike, input: DeliveryEventInput): number | null;
+/** A session's delivery events in write order, each with its candidate rows; `sessionId` null reads session-less events. */
+export declare function readDeliveryEvents(db: DatabaseSyncLike, tenantId: string, sessionId: string | null): DeliveryEventRow[];
 //# sourceMappingURL=recall-trace.d.ts.map

package/dist/recall-trace.js

@@ -17,6 +17,7 @@
  */
 import { createHash } from 'node:crypto';
 import { openHippoDb, closeHippoDb } from './db.js';
+import { DELIVERY_LEDGER_VERSION } from './delivery-recorder.js';
 /**
  * Strip a RerankStep down to {stage, multiplier, scoreBefore, scoreAfter}
  * before persisting (F3 privacy fix, codex cross-model finding). `note` is
@@ -183,4 +184,139 @@ export function recordTraceOutcome(db, input) {
         console.error(`[hippo] recall trace outcome write failed: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+/** Pruned on write, counted back from the event's ts capped at the real clock, so a far-future fake time spares real rows. */
+export const DELIVERY_LEDGER_RETENTION_DAYS = 90;
+/** Lock wait for the ledger's own connection: a busy store drops the row rather than slow the hook. */
+export const DELIVERY_LEDGER_WAIT_MS = 50;
+/** Two prompt-identical events without a host turn id this close together are one turn fired twice. */
+export const DELIVERY_DUPLICATE_WINDOW_MS = 2000;
+const DELIVERY_EVENT_COLUMNS = [
+    'ts', 'ledger_version', 'tenant_id', 'runtime', 'event_type', 'surface', 'store_hash', 'write_store', 'project_hash',
+    'session_id', 'session_state', 'host_turn_id', 'turn_seq', 'duplicate_of', 'prompt_hash', 'prompt_length', 'query_hash',
+    'recall_trace_id', 'block_state', 'prompt_recall', 'considered_count', 'filtered_count', 'selected_count', 'emitted_count',
+    'rejected_count', 'rejected_unlisted', 'sections_shown', 'sections_dropped', 'budget_tokens', 'selected_tokens',
+    'injected_tokens', 'static_hash', 'recall_hash', 'emitted_hash', 'elapsed_ms',
+];
+function findDuplicateTurn(db, input) {
+    if (input.hostTurnId !== null) {
+        // SAFETY: a single `id` column, undefined when no row matches.
+        const row = db.prepare(`
+      SELECT id FROM delivery_events
+      WHERE tenant_id = ? AND session_id = ? AND event_type = ? AND host_turn_id = ? AND turn_seq IS NOT NULL
+      ORDER BY id LIMIT 1
+    `).get(input.tenantId, input.sessionId, input.eventType, input.hostTurnId);
+        return row?.id ?? null;
+    }
+    if (input.promptHash === null)
+        return null;
+    // SAFETY: rows carry exactly the `id` and `ts` columns selected.
+    const rows = db.prepare(`
+    SELECT id, ts FROM delivery_events
+    WHERE tenant_id = ? AND session_id = ? AND event_type = ? AND prompt_hash = ? AND host_turn_id IS NULL AND turn_seq IS NOT NULL
+    ORDER BY id
+  `).all(input.tenantId, input.sessionId, input.eventType, input.promptHash);
+    const at = Date.parse(input.ts);
+    // Absolute difference: two hook processes can commit out of ts order.
+    return rows.find((r) => Math.abs(Date.parse(r.ts) - at) <= DELIVERY_DUPLICATE_WINDOW_MS)?.id ?? null;
+}
+function nextTurnSeq(db, input) {
+    // SAFETY: a single MAX aggregate aliased `m`, NULL when the session has no turns yet.
+    const row = db.prepare(`
+    SELECT MAX(turn_seq) AS m FROM delivery_events
+    WHERE tenant_id = ? AND session_id = ? AND event_type = ? AND turn_seq IS NOT NULL
+  `).get(input.tenantId, input.sessionId, input.eventType);
+    return (row.m ?? 0) + 1;
+}
+/** One event plus its candidates in one write transaction, then prune; fail-soft. The caller must not hold a transaction on `db`. */
+export function writeDeliveryEvent(db, input) {
+    try {
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            // Missing-session and sub-agent events are not turns of a session, so they get no number and no duplicate check.
+            const isTurn = input.sessionId !== null && (input.sessionState === 'payload' || input.sessionState === 'env');
+            const duplicateOf = isTurn ? findDuplicateTurn(db, input) : null;
+            const turnSeq = isTurn && duplicateOf === null ? nextTurnSeq(db, input) : null;
+            const values = [
+                input.ts, DELIVERY_LEDGER_VERSION, input.tenantId, input.runtime, input.eventType, input.surface, input.storeHash,
+                input.writeStore, input.projectHash, input.sessionId, input.sessionState, input.hostTurnId, turnSeq, duplicateOf,
+                input.promptHash, input.promptLength, input.queryHash, input.recallTraceId, input.blockState, input.promptRecall ? 1 : 0,
+                input.consideredCount, input.filteredCount, input.selectedCount, input.emittedCount, input.rejectedCount,
+                input.rejectedUnlisted, input.sectionsShown, input.sectionsDropped, input.budgetTokens, input.selectedTokens,
+                input.injectedTokens, input.staticHash, input.recallHash, input.emittedHash, Math.round(input.elapsedMs),
+            ];
+            const eventId = Number(db.prepare(`
+        INSERT INTO delivery_events (${DELIVERY_EVENT_COLUMNS.join(', ')})
+        VALUES (${DELIVERY_EVENT_COLUMNS.map(() => '?').join(', ')})
+      `).run(...values).lastInsertRowid);
+            const insertCandidate = db.prepare(`
+        INSERT INTO delivery_candidates (event_id, tenant_id, memory_id, source_store, pool, stage, outcome, reason, cand_rank, score, tokens)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `);
+            for (const c of input.candidates) {
+                insertCandidate.run(eventId, input.tenantId, c.memoryId, c.sourceStore, c.pool, c.stage, c.outcome, c.reason, c.rank, c.score, c.tokens);
+            }
+            const pruneFrom = Math.min(Date.parse(input.ts), Date.now());
+            const cutoff = new Date(pruneFrom - DELIVERY_LEDGER_RETENTION_DAYS * 86_400_000).toISOString();
+            db.prepare(`DELETE FROM delivery_events WHERE ts < ?`).run(cutoff);
+            db.exec('COMMIT');
+            return eventId;
+        }
+        catch (error) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { /* SQLite may already have rolled back (SQLITE_FULL, IOERR); keep the original error */ }
+            throw error;
+        }
+    }
+    catch (error) {
+        // eslint-disable-next-line no-console
+        console.error(`[hippo] delivery ledger write failed: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+/** Write on a short-lived connection that waits at most {@link DELIVERY_LEDGER_WAIT_MS} for the lock. Fail-soft. */
+export function writeDeliveryEventAtRoot(root, input) {
+    let db;
+    try {
+        db = openHippoDb(root, { busyWaitMs: DELIVERY_LEDGER_WAIT_MS });
+    }
+    catch (error) {
+        // eslint-disable-next-line no-console
+        console.error(`[hippo] delivery ledger write failed: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+    try {
+        return writeDeliveryEvent(db, input);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** On a caller's open handle, which saves a second open and close per turn; the handle's own lock wait comes back after. */
+export function writeDeliveryEventOnHandle(db, input) {
+    const prior = Math.trunc(Number(db.prepare('PRAGMA busy_timeout').get().timeout));
+    db.exec(`PRAGMA busy_timeout = ${DELIVERY_LEDGER_WAIT_MS}`);
+    try {
+        return writeDeliveryEvent(db, input);
+    }
+    finally {
+        db.exec(`PRAGMA busy_timeout = ${prior}`);
+    }
+}
+/** A session's delivery events in write order, each with its candidate rows; `sessionId` null reads session-less events. */
+export function readDeliveryEvents(db, tenantId, sessionId) {
+    // SAFETY: SELECT * over delivery_events returns exactly the columns DeliveryEventRow names, less `candidates`.
+    const events = db.prepare(`SELECT * FROM delivery_events WHERE tenant_id = ? AND session_id IS ? ORDER BY id`)
+        .all(tenantId, sessionId);
+    const candidates = db.prepare(`
+    SELECT * FROM delivery_candidates WHERE event_id = ?
+    ORDER BY outcome = 'rejected', cand_rank, memory_id
+  `);
+    return events.map((e) => ({
+        ...e,
+        // SAFETY: SELECT * over delivery_candidates returns exactly the columns DeliveryCandidateRow names.
+        candidates: candidates.all(e.id),
+    }));
+}
 //# sourceMappingURL=recall-trace.js.map

package/dist/token-ledger.d.ts

@@ -116,6 +116,8 @@ interface ModelTagged {
 export declare function isSyntheticMessage(message: ModelTagged): boolean;
 /** A hook payload's non-empty `session_id`, or null; with `requiredSource`, also null when its `source` differs. */
 export declare function hookPayloadSessionId(stdinText: string | undefined, requiredSource?: string | null): string | null;
+/** A hook payload's string `field` as sent, or null when the payload or the field is missing or not a string. */
+export declare function hookPayloadString(stdinText: string | undefined, field: string): string | null;
 /** Whether a hook fired inside a sub-agent, the only payload with `agent_id` (https://code.claude.com/docs/en/hooks#common-input-fields).
  *  Its `session_id` is the parent's, so a sub-agent's blocks and compactions must not count as the parent's. */
 export declare function isSubagentPayload(stdinText: string | undefined): boolean;

package/dist/token-ledger.js

@@ -174,6 +174,11 @@ export function hookPayloadSessionId(stdinText, requiredSource = null) {
         return null;
     return sessionId;
 }
+/** A hook payload's string `field` as sent, or null when the payload or the field is missing or not a string. */
+export function hookPayloadString(stdinText, field) {
+    const value = parseHookPayload(stdinText)?.[field];
+    return isJsonString(value) ? value : null;
+}
 /** Whether a hook fired inside a sub-agent, the only payload with `agent_id` (https://code.claude.com/docs/en/hooks#common-input-fields).
  *  Its `session_id` is the parent's, so a sub-agent's blocks and compactions must not count as the parent's. */
 export function isSubagentPayload(stdinText) {

package/dist/version.d.ts

@@ -16,7 +16,7 @@
  * an ESM `import` can resolve cleanly, and a hardcoded constant survives
  * any packager that drops .json files.
  */
-export declare const PACKAGE_VERSION = "1.55.0";
+export declare const PACKAGE_VERSION = "1.56.0";
 /** Compares plain x.y.z versions, positive if a > b; tags throw so the rollback guard never misfires silently. */
 export declare function compareSemver(a: string, b: string): number;
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -16,7 +16,7 @@
  * an ESM `import` can resolve cleanly, and a hardcoded constant survives
  * any packager that drops .json files.
  */
-export const PACKAGE_VERSION = '1.55.0';
+export const PACKAGE_VERSION = '1.56.0';
 /** Compares plain x.y.z versions, positive if a > b; tags throw so the rollback guard never misfires silently. */
 export function compareSemver(a, b) {
     const parse = (v) => {

package/extensions/openclaw-plugin/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "hippo-memory",
   "name": "Hippo Memory",
   "description": "Memory for AI agents that learns what is wrong and ranks it down. Injects context at session start and captures errors.",
-  "version": "1.55.0",
+  "version": "1.56.0",
 
   "configSchema": {
     "type": "object",

package/extensions/openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "1.55.0",
+  "version": "1.56.0",
   "type": "module",
   "description": "Hippo Memory plugin for OpenClaw - biologically-inspired agent memory",
   "main": "index.ts",

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "hippo-memory",
   "name": "Hippo Memory",
   "description": "Memory for AI agents that learns what is wrong and ranks it down. Injects context at session start and captures errors.",
-  "version": "1.55.0",
+  "version": "1.56.0",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "1.55.0",
+  "version": "1.56.0",
   "description": "Memory for AI agents that learns what is wrong and ranks it down. MCP server, hooks for Claude Code, OpenCode and Codex, AGENTS.md instructions for Codex, Cursor, OpenClaw and Pi. SQLite, zero runtime deps.",
   "mcpName": "io.github.kitfunso/hippo-memory",
   "type": "module",
@@ -34,6 +34,7 @@
     "pretest": "npm run build",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:delivery-ledger": "vitest run tests/delivery-ledger",
     "lint": "oxlint",
     "sbom": "node scripts/sbom.mjs",
     "audit:security": "npm audit --audit-level=high && npm --prefix ui audit --audit-level=high",