hippo-memory 1.54.0 → 1.56.0

package/README.md

@@ -118,7 +118,7 @@ Run `hippo init` inside one project. This is everything it writes, in the projec
 - **Instruction files.** A block between `<!-- hippo:start -->` and `<!-- hippo:end -->` in the project's `CLAUDE.md` or `AGENTS.md`, only if that file already exists. Codex, Cursor, OpenClaw, OpenCode and Pi read `AGENTS.md`.
 - **Claude Code,** when the project has `CLAUDE.md` or `.claude/settings.json`: 7 hook entries in `~/.claude/settings.json`, one each on SessionEnd, UserPromptSubmit, PreCompact, PostCompact and PostToolUseFailure and two on SessionStart. [Framework Integrations](#framework-integrations) says what each one runs.
 - **OpenCode,** when the project has `.opencode/` or `opencode.json`: a plugin at `~/.config/opencode/plugins/hippo.ts`.
-- **Codex,** when the project has `AGENTS.md` or `.codex` and Codex is installed (`$CODEX_HOME`, else `~/.codex`, exists): 2 hook entries in Codex's `hooks.json`, one on UserPromptSubmit that sends your pinned memories plus the five most recent ones with every prompt and one on SessionStart after a compaction. **Codex runs them only after you trust them once in `/hooks`.** Init also prints `hippo hook install codex`, the opt-in that wraps the Codex launcher to capture sessions; `hippo hook uninstall codex` removes hippo's hooks and the wrapper.
+- **Codex,** when the project has `AGENTS.md` or `.codex` and Codex is installed (`$CODEX_HOME`, else `~/.codex`, exists): 2 hook entries in Codex's `hooks.json`, one on UserPromptSubmit that sends your pinned memories plus up to 5 that match the prompt with every prompt and one on SessionStart after a compaction. **Codex runs them only after you trust them once in `/hooks`.** Init also prints `hippo hook install codex`, the opt-in that wraps the Codex launcher to capture sessions; `hippo hook uninstall codex` removes hippo's hooks and the wrapper.
 - **A daily run at 6:15am,** one per machine: a crontab line on Linux and macOS, a scheduled task named `hippo-daily-runner` on Windows. It runs `hippo learn --git --days 1` and then `hippo sleep` in every project listed in `~/.hippo/workspaces.json`, and init adds this project to that list.
 - **Agent memories.** On every run, the notes your coding agents keep about this project go into its store, and the ones about you go into the global store. [Agent memories](#agent-memories) lists what is read.
 
@@ -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
@@ -783,7 +794,7 @@ The block asks for nothing a hook already does, because each extra tool call re-
 For Claude Code, it also adds 7 hook entries to `~/.claude/settings.json`:
 - a `SessionEnd` hook that runs `hippo sleep` and then `hippo capture` when the session exits. Capture matches the last 20 user and 10 assistant messages of the transcript against word patterns for decisions, rules, errors and preferences. It uses no model and does not read earlier turns, so record lessons with `hippo remember` as you go.
 - a `SessionStart` hook that prints the previous session's consolidation output
-- a `UserPromptSubmit` hook that runs `hippo context --pinned-only --include-recent 5 --format additional-context` every turn. It re-injects pinned memories (`hippo remember <text> --pin`) plus the 5 newest memories in the store, so fresh same-session lessons appear on the next prompt before you pin them. It does not read your prompt unless you set `{"pinnedInject":{"promptRecall":true}}`, which swaps the 5 newest for memories that match the prompt. The block is rendered without live strength percentages, so it stays byte-identical while its memories do not change, and it is sent only when it changed since the session's last prompt: an unchanged block is skipped, resent every 10 skips (`pinnedInject.refreshTurns`, `0` never resends) and resent after compaction. `{"pinnedInject":{"skipUnchanged":false}}` sends it every turn as before. Opt out entirely with `{"pinnedInject":{"enabled":false}}` in `.hippo/config.json`.
+- a `UserPromptSubmit` hook that runs `hippo context --pinned-only --include-recent 5 --format additional-context` every turn. It re-injects pinned memories (`hippo remember <text> --pin`) plus up to 5 memories that share words with your prompt. When nothing matches, it adds only the pinned ones. Since 1.55.0 this replaces the 5 newest memories, which cut the median block from 847 to 533 tokens in our eval. `{"pinnedInject":{"promptRecall":false}}` brings back the 5 newest, so fresh same-session lessons appear on the next prompt whatever you ask. The block is rendered without live strength percentages, so it stays byte-identical while its memories do not change, and it is sent only when it changed since the session's last prompt: an unchanged block is skipped, resent every 10 skips (`pinnedInject.refreshTurns`, `0` never resends) and resent after compaction. The prompt-matched memories go in a separate block that is never skipped, so they are sent on every prompt they match. `{"pinnedInject":{"skipUnchanged":false}}` sends the pinned block every turn as before. Opt out entirely with `{"pinnedInject":{"enabled":false}}` in `.hippo/config.json`.
 - a `PreCompact` hook that runs `hippo pre-compact` before the transcript gets summarized. It records the compaction in the store, saves a working-state snapshot (task/summary/next step) so mid-session compaction can't drop it, and asks the summariser to end its summary with a "Memories for hippo" list: the lessons, decisions and corrections from the session that should outlive it. The `SessionEnd` hook still owns extracting durable memories from the transcript.
 - a second `SessionStart` hook (matcher `compact`) that runs `hippo compact-resume`, printing that snapshot back into context right after compaction, if it is under 15 minutes old.
 - a `PostCompact` hook that runs `hippo post-compact`. It keeps the summary in the store with secrets scrubbed, and saves each item of that list as a memory that sleep never deletes: at most 10 per compaction, skipping an item an earlier compaction already saved and any item that looks like a secret. An item over 500 characters stays in the compaction's record only. It then prints one line, such as "Hippo saved 3 memories from this compaction and restored your task snapshot." If the store is busy, the summary waits in the store's `compactions-spool/` folder and `hippo sleep` finishes the save; `hippo doctor` names any compaction left unfinished for over 10 minutes. The session that compacted does not have those memories injected back into its own prompts, since it just read them in the summary; `hippo recall` still finds them. The hook prints nothing when there is no store to save to.
@@ -794,7 +805,7 @@ Only Claude Code saves memories at a compaction: hippo installs no `PreCompact`
 To remove: `hippo hook uninstall claude-code`
 
 For Codex, it adds two hooks to `$CODEX_HOME/hooks.json` (else `~/.codex/hooks.json`) and keeps every hook already there:
-- a `UserPromptSubmit` hook that runs the same `hippo context --pinned-only` command as Claude Code's, so your pinned memories plus the five most recent ones reach every prompt as developer context
+- a `UserPromptSubmit` hook that runs the same `hippo context --pinned-only` command as Claude Code's, so your pinned memories plus up to 5 that match the prompt reach every prompt as developer context
 - a `SessionStart` hook (matcher `compact`) that runs `hippo compact-resume` after a compaction, so the next prompt sends that block again. Codex gets no `PreCompact` hook from hippo, so it restores a task snapshot only if one was saved with `hippo snapshot save` in the last 15 minutes
 
 **Codex runs a new or changed hook only after you trust it, so open `/hooks` in Codex once and trust both;** `hippo doctor` reminds you. The per-prompt hook was checked against a real Codex request; the compaction hook follows Codex's documented `compact` start source and has not been watched end to end in Codex. Each hook also carries a `commandWindows` form (`hippo.cmd ...`), because Codex runs hooks through PowerShell on Windows, where the execution policy can block npm's `hippo.ps1`. hippo only ever appends these two entries and never rewrites one, since Codex treats a changed command as a new hook to trust. To remove: `hippo hook uninstall codex`, which takes out only hippo's exact commands and leaves every other hook, including one of yours that runs hippo.
@@ -1056,7 +1067,7 @@ node run.mjs --adapter all
 
 ### How do I give Claude Code memory between sessions?
 
-Run `npm install -g hippo-memory`, then `hippo init` in the project. If the project has a `CLAUDE.md`, init adds a short block telling Claude to run `hippo context --auto` when a session starts. It also adds 7 hook entries to Claude Code's settings that keep your pinned memories plus the five most recent ones in context, save a task snapshot and the memories a compaction summary lists, store failed tool calls as lessons, and run `hippo sleep` when the session ends, and it sets up a daily 6:15am run. [What hippo init changes](#what-hippo-init-changes) lists everything. The [Claude Code plugin](https://github.com/kitfunso/hippo-memory/tree/master/extensions/claude-code-plugin) is the alternative to these hooks; use one, not both. To set up every git repo up to three folders below your home directory at once, know what the scan changes first: each repo gets its own store, seeded from a year of its git history, the same hooks go in when one of those repos uses Claude Code, and the daily run is set up, but no block goes into any repo's `CLAUDE.md`. The command is `hippo init --scan ~`; run `hippo init` in the projects where you want the block.
+Run `npm install -g hippo-memory`, then `hippo init` in the project. If the project has a `CLAUDE.md`, init adds a short block telling Claude to run `hippo context --auto` when a session starts. It also adds 7 hook entries to Claude Code's settings that keep your pinned memories plus up to 5 that match the prompt in context, save a task snapshot and the memories a compaction summary lists, store failed tool calls as lessons, and run `hippo sleep` when the session ends, and it sets up a daily 6:15am run. [What hippo init changes](#what-hippo-init-changes) lists everything. The [Claude Code plugin](https://github.com/kitfunso/hippo-memory/tree/master/extensions/claude-code-plugin) is the alternative to these hooks; use one, not both. To set up every git repo up to three folders below your home directory at once, know what the scan changes first: each repo gets its own store, seeded from a year of its git history, the same hooks go in when one of those repos uses Claude Code, and the daily run is set up, but no block goes into any repo's `CLAUDE.md`. The command is `hippo init --scan ~`; run `hippo init` in the projects where you want the block.
 
 ### How do I give Cursor memory between sessions?
 
@@ -1064,7 +1075,7 @@ Run `npm install -g hippo-memory`, then `hippo init` in the project. If the proj
 
 ### How do I give Codex memory across sessions?
 
-`hippo init` adds its instructions to your `AGENTS.md`, which Codex reads before it starts work. When Codex is installed, init also adds two hooks to Codex's `hooks.json`: one puts your pinned memories plus the five most recent ones into every prompt, the other makes the next prompt send them again after a compaction. Codex asks you to trust each new hook once in `/hooks`, and skips it until you do. Capturing Codex sessions is opt-in: `hippo hook install codex` wraps the Codex launcher, and `hippo hook uninstall codex` removes the wrapper and the hooks.
+`hippo init` adds its instructions to your `AGENTS.md`, which Codex reads before it starts work. When Codex is installed, init also adds two hooks to Codex's `hooks.json`: one puts your pinned memories plus up to 5 that match the prompt into every prompt, the other makes the next prompt send them again after a compaction. Codex asks you to trust each new hook once in `/hooks`, and skips it until you do. Capturing Codex sessions is opt-in: `hippo hook install codex` wraps the Codex launcher, and `hippo hook uninstall codex` removes the wrapper and the hooks.
 
 ### Which agents does hippo work with?
 

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);
+        });
     }
 }
 /**
@@ -8773,7 +8846,7 @@ Commands:
     --budget <n>           Token budget for the whole printed block (default: 1500)
     --pinned-only          Only inject pinned memories (used by UserPromptSubmit hook)
     --include-recent <n>   With --pinned-only, also inject the last N writes regardless of pinning
-    (the hook payload's "prompt" drives prompt recall instead of --include-recent when pinnedInject.promptRecall is on)
+    (the hook payload's "prompt" drives prompt recall instead of --include-recent when pinnedInject.promptRecall is on, the default)
     --format <fmt>         Output format: markdown (default), json, or additional-context (Claude Code hook JSON)
     --framing <mode>       Framing: observe (default), suggest, assert
   sleep                    Run consolidation pass (auto-learns + dedup + auto-shares)

package/dist/config.d.ts

@@ -71,8 +71,8 @@ export interface HippoConfig {
          *  never resends an unchanged block. */
         refreshTurns: number;
         /** Z1: gate the hook's backfill on the prompt's own content instead of
-         *  the five newest memories. Default false: the eval failed its overlap gate
-         *  (docs/evals/2026-09-26-z1-prompt-recall-result.md). */
+         *  the five newest memories. Default true since 1.55.0: overlap tied but median
+         *  tokens fell 847 to 533 (docs/evals/2026-09-26-z1-prompt-recall-result.md). */
         promptRecall: boolean;
         /** Z1: overlap metric for the prompt-recall gate. Default 'jaccard' (tuned, docs/evals/2026-09-26-z1-prompt-recall-result.md). */
         promptRecallMetric: PromptRecallMetric;
@@ -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

@@ -47,7 +47,7 @@ const DEFAULT_CONFIG = {
         budget: 1500,
         skipUnchanged: true,
         refreshTurns: 10,
-        promptRecall: false,
+        promptRecall: true,
         promptRecallMetric: 'jaccard',
         promptRecallThreshold: 0.04,
         promptRecallMinShared: 2,
@@ -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))