hippo-memory 1.52.8 → 1.53.0

package/dist/api.js

@@ -17,7 +17,7 @@ import { detectInstruction } from './instruction-detect.js';
 import { quarantineScopeFor, recordQuarantine, getQuarantineRow, listQuarantineRows, approveQuarantineRow, rejectQuarantineRow, } from './quarantine.js';
 import { summarizeFailures } from './failure-log.js';
 import { formatHandoffEvidenceLine } from './handoff.js';
-import { createMemory, applyOutcome, calculateStrength, Layer, CHURN_STALE_TAG, } from './memory.js';
+import { createMemory, createSuccessor, applyOutcome, calculateStrength, CHURN_STALE_TAG, COMPACTION_MEMORY_TAG, } from './memory.js';
 import { appendAuditEvent, queryAuditEvents, auditMemories, isContentWorthStoring, } from './audit.js';
 import { promoteToGlobal, getGlobalRoot, autoShare, searchBothHybrid } from './shared.js';
 import { writeRecallTrace, writeRecallTraceAtRoot, recordTraceOutcome } from './recall-trace.js';
@@ -27,12 +27,14 @@ import { createApiKey, listApiKeys, revokeApiKey, grantScope, ungrantScope, } fr
 import { applyGoalStackBoost } from './goals.js';
 import { markRetrieved, estimateTokens, hybridSearch, physicsSearch, churnStaleFactor } from './search.js';
 import { compareEntryIdentity, compareScoredResults } from './compare.js';
+import { dropHeldCopies, duplicateKey, storedTextKeys } from './same-text.js';
 import { scopeMatch } from './scope.js';
 import { consolidate } from './consolidate.js';
 import { loadConfig } from './config.js';
 import { resolveProjectIdentity, classifyOriginProject, isGlobalStoreRoot } from './project-identity.js';
 import { promptTokens, contentTokens, gatePromptRecall, } from './prompt-recall.js';
 import { detectSecret } from './secret-detect.js';
+import { isSessionDigestRow } from './session-digest.js';
 import { deduplicateStore } from './dedupe.js';
 import { computeAmbientState } from './ambient.js';
 import { loadPendingExtractionTenants, markPendingProcessedUpTo } from './graph.js';
@@ -425,6 +427,13 @@ function recallFrom(ctx, opts, windowSize, all) {
                 }));
             }
         }
+        if (!opts.keepHeldCopies) {
+            const shownIds = new Set(dropHeldCopies([...baseScored.map((r) => r.entry), ...substituted.map((s) => s.entry)], (e) => e).map((e) => e.id));
+            droppedPreRankCount += baseScored.filter((r) => !shownIds.has(r.entry.id)).length;
+            baseScored = baseScored.filter((r) => shownIds.has(r.entry.id));
+            baseSlice = baseScored.map((r) => r.entry);
+            substituted = substituted.filter((s) => shownIds.has(s.entry.id));
+        }
         // v1.12.13 / C5 — WYSIATI summary_substitutions_added counter.
         summarySubstitutionsCount = substituted.length;
         // v1.7.4 -- baseScored carries the (possibly boosted) per-row scores. When
@@ -498,9 +507,11 @@ function recallFrom(ctx, opts, windowSize, all) {
                 ...baseRanked.map((r) => r.id),
                 ...summaryRanked.map((r) => r.id),
             ]);
+            const shownKeys = storedTextKeys(opts.keepHeldCopies ? [] : [...baseSlice, ...substituted.map((s) => s.entry)]);
             for (const m of recentScoped) {
-                if (seenIds.has(m.id))
+                if (seenIds.has(m.id) || shownKeys.has(duplicateKey(m.content)))
                     continue;
+                shownKeys.add(duplicateKey(m.content));
                 const item = {
                     id: m.id,
                     content: m.content,
@@ -626,10 +637,7 @@ function recallFrom(ctx, opts, windowSize, all) {
     // per-pipeline). opts.actor threads through to the inner
     // computePredictionBaserate call so MCP/HTTP-originated hints attribute
     // correctly instead of defaulting to 'cli'. Disabled by HIPPO_AUTODEBIAS=off.
-    // v1.13.4: switched from computePlanningFallacyHint to
-    // computePlanningFallacyOutput so the no-class-match / tiebreak
-    // watching variant can also reach the caller surface. The two
-    // outputs are mutually exclusive; we splat both as optional fields.
+    // The hint and the no-class-match / tiebreak watching variant are mutually exclusive; both go out as optional fields.
     const planningFallacyOutput = computePlanningFallacyOutput(ctx.hippoRoot, ctx.tenantId, opts.query, { actor: ctx.actor.subject });
     const planningFallacyHint = planningFallacyOutput.hint ?? null;
     const planningFallacyWatching = planningFallacyOutput.watching ?? null;
@@ -869,9 +877,11 @@ export function assemble(ctx, sessionId, opts = {}) {
     olderItems.sort((a, b) => cmpIso(a.createdAt, b.createdAt));
     tailItems.sort((a, b) => cmpIso(a.createdAt, b.createdAt));
     let items = [...olderItems, ...tailItems];
-    let tokens = items.reduce((acc, it) => acc + estimateTokens(it.content), 0);
+    const itemCost = opts.cost?.item ?? ((it) => estimateTokens(it.content));
+    const room = budget - (opts.cost?.fixed(Math.max(budget, totalRaw)) ?? 0);
+    let tokens = items.reduce((acc, it) => acc + itemCost(it), 0);
     let evicted = 0;
-    while (tokens > budget && items.length > 0) {
+    while (tokens > room && items.length > 0) {
         let worstIdx = -1;
         let worstStrength = Infinity;
         for (let i = 0; i < items.length; i++) {
@@ -884,7 +894,7 @@ export function assemble(ctx, sessionId, opts = {}) {
         }
         if (worstIdx === -1)
             break;
-        const cost = estimateTokens(items[worstIdx].content);
+        const cost = itemCost(items[worstIdx]);
         items = items.filter((_, i) => i !== worstIdx);
         tokens -= cost;
         evicted++;
@@ -961,15 +971,32 @@ export function drillDown(ctx, summaryId, opts = {}) {
             break;
         frontier = nextFrontier;
     }
+    const summaryOut = {
+        id: summary.id,
+        content: summary.content,
+        // v0.30 / E5: the STORED direct-child count; the legacy fallback counts
+        // level-0 children, never the BFS-depth-N total (independent-review MED #4).
+        descendantCount: summary.descendant_count ?? level0DirectCount,
+        earliestAt: summary.earliest_at ?? null,
+        latestAt: summary.latest_at ?? null,
+    };
+    const all = collected.map((c) => ({
+        id: c.id,
+        content: c.content,
+        layer: c.layer,
+        dagLevel: c.dag_level ?? 0,
+        created: c.created,
+    }));
     // Apply global cumulative token budget + limit cap on collected.
-    let children = collected;
+    let children = all;
     let truncated = false;
     if (opts.budget !== undefined) {
         const out = [];
         let used = 0;
-        for (const c of collected) {
-            const t = estimateTokens(c.content);
-            if (out.length > 0 && used + t > opts.budget) {
+        const room = opts.budget - (opts.cost?.fixed(summaryOut, all.length) ?? 0);
+        for (const c of all) {
+            const t = opts.cost ? opts.cost.child(c) : estimateTokens(c.content);
+            if (out.length > 0 && used + t > room) {
                 truncated = true;
                 break;
             }
@@ -983,25 +1010,8 @@ export function drillDown(ctx, summaryId, opts = {}) {
         truncated = true;
     }
     return {
-        summary: {
-            id: summary.id,
-            content: summary.content,
-            // v0.30 / E5: descendant_count stays the summary's STORED value
-            // (direct children at creation time). totalChildren below reflects
-            // the full BFS collection at the requested depth.
-            // independent-review MED #4 fold: legacy fallback uses level-0 direct
-            // count (NOT collected.length which is BFS-depth-N total).
-            descendantCount: summary.descendant_count ?? level0DirectCount,
-            earliestAt: summary.earliest_at ?? null,
-            latestAt: summary.latest_at ?? null,
-        },
-        children: children.map((c) => ({
-            id: c.id,
-            content: c.content,
-            layer: c.layer,
-            dagLevel: c.dag_level ?? 0,
-            created: c.created,
-        })),
+        summary: summaryOut,
+        children,
         // v0.30 / E5: totalChildren = BFS-collected count (depth-aware). For
         // depth=1 this equals the eligible direct-children count (backward
         // compat). For depth>1 it is the cumulative count across levels.
@@ -1192,14 +1202,8 @@ export function supersede(ctx, oldId, newContent) {
     if (old.superseded_by) {
         throw new Error(`Memory ${oldId} is already superseded by ${old.superseded_by}. Supersede that one instead.`);
     }
-    const newEntry = createMemory(newContent, {
-        layer: old.layer ?? Layer.Episodic,
-        tags: [...old.tags],
-        pinned: old.pinned,
-        source: old.source,
-        confidence: 'verified',
+    const newEntry = createSuccessor(old, newContent, {
         tenantId: ctx.tenantId,
-        scope: old.scope,
         baseHalfLifeDays: loadConfig(ctx.hippoRoot).defaultHalfLifeDays,
     });
     // Race-safe transition: open a fresh db handle, BEGIN IMMEDIATE, run all
@@ -1539,13 +1543,13 @@ export async function getContext(ctx, opts = {}) {
     if (budget <= 0) {
         return { entries: [], tokens: 0 };
     }
-    // Pinned-only path is allowed against an un-initialised local store (the
-    // UserPromptSubmit hook can run in directories without a .hippo). Non-pinned
-    // path requires an initialised local store; callers should check first.
+    // Global memories do not establish a project boundary for task state.
     const hasLocal = isInitialized(ctx.hippoRoot);
     const query = (opts.q ?? '').trim() || '*';
     const globalRoot = getGlobalRoot();
     const hasGlobal = isInitialized(globalRoot);
+    const primaryIsGlobal = isGlobalStoreRoot(ctx.hippoRoot);
+    const hasLocalTaskState = hasLocal && !primaryIsGlobal;
     // v39 memory scope isolation (docs/plans/2026-07-01-memory-scope-isolation.md).
     // S2: envelope-filter parity with api.recall for AMBIENT context - private
     // scopes and quarantine buckets never inject. `requested` is deliberately
@@ -1557,11 +1561,6 @@ export async function getContext(ctx, opts = {}) {
     const isolationEnabled = config.contextProjectIsolation !== false;
     const currentProjectName = opts.currentProject ?? resolveProjectIdentity(process.cwd()).name;
     const includeCrossProject = opts.crossProject === true || !isolationEnabled;
-    const ambientAdmit = (e) => ambientAdmitEntry(e, currentProjectName, includeCrossProject);
-    // Superseded rows never inject, and ambientAdmitEntry regex-scans content for
-    // secrets, so WHICH rows reach this predicate is what loadAmbientEntries cares
-    // about below.
-    const admit = (e) => !e.superseded_by && ambientAdmit(e);
     // Z1: decided before the ambient loads so the FTS candidate query below (pinned-only
     // branch) can piggyback on that connection instead of opening its own.
     const promptRecallPending = pinnedOnly && Boolean(opts.prompt?.trim()) && config.pinnedInject.promptRecall === true;
@@ -1571,18 +1570,21 @@ export async function getContext(ctx, opts = {}) {
     const recallRequest = promptRecallTerms.length > 0
         ? { terms: promptRecallTerms, limit: Math.floor(finiteOr(config.pinnedInject.promptRecallCandidates, 100, 1)) }
         : undefined;
-    // Tenant-scoped loads (v1.11.1 lesson: NEVER resolveTenantId({}) here).
-    const localLoad = hasLocal
-        ? loadAmbientEntries(ctx.hippoRoot, ctx.tenantId, pinnedOnly, includeRecent, admit, recallRequest)
-        : { entries: [] };
-    const globalLoad = hasGlobal
-        ? loadAmbientEntries(globalRoot, ctx.tenantId, pinnedOnly, includeRecent, admit, !isGlobalStoreRoot(ctx.hippoRoot) ? recallRequest : undefined)
-        : { entries: [] };
-    let localEntries = localLoad.entries;
-    let globalEntries = globalLoad.entries;
-    // Computed below, after markRetrieved runs, so avgStrength reflects the
-    // post-retrieval strengths rather than a stale pre-mutation snapshot.
-    let ambientState;
+    const cost = opts.cost;
+    const price = (entry, isGlobal, promptRecall) => cost
+        ? cost.entry({ entry, isGlobal, promptRecall, origin: entry.origin_project ?? null, category: classifyOriginProject(entry.origin_project, currentProjectName) })
+        : estimateTokens(entry.content);
+    const blockBudget = pinnedOnly && opts.budget === undefined ? config.pinnedInject.budget : budget;
+    let left = cost
+        ? Math.max(0, blockBudget - cost.fixed(blockBudget, { cross: includeCrossProject, promptRecall: promptRecallPending, ambient: !pinnedOnly && config.ambient.enabled }))
+        : blockBudget;
+    // Sections print ahead of the memories, so they are paid first; one that does not fit is dropped, as an oversize entry is.
+    const pays = (tokens) => {
+        if (tokens > left)
+            return false;
+        left -= tokens;
+        return true;
+    };
     // DF1 T2: bounded read — an orphaned snapshot (no later pre-compact
     // superseded it, no session-end closed it) must age out of this ambient
     // surface instead of injecting into every future prompt forever. Owner
@@ -1590,7 +1592,7 @@ export async function getContext(ctx, opts = {}) {
     // unbounded; see loadFreshActiveTaskSnapshot's own doc comment for the
     // exact null/empty-id matching rules.
     const rowScope = (r) => r?.scope ?? null;
-    const rawActiveSnapshot = hasLocal
+    const rawActiveSnapshot = hasLocalTaskState
         ? loadFreshActiveTaskSnapshot(ctx.hippoRoot, ctx.tenantId, {
             sessionId: opts.currentSessionId,
         })
@@ -1601,7 +1603,7 @@ export async function getContext(ctx, opts = {}) {
         ? rawActiveSnapshot
         : null;
     // Key on the RAW snapshot: a scope-hidden active session must not fall through to another session's ambient handoff.
-    const rawSessionHandoff = !hasLocal
+    const rawSessionHandoff = !hasLocalTaskState
         ? null
         : rawActiveSnapshot?.session_id
             ? loadLatestHandoff(ctx.hippoRoot, ctx.tenantId, rawActiveSnapshot.session_id)
@@ -1615,18 +1617,49 @@ export async function getContext(ctx, opts = {}) {
         ? rawSessionHandoff
         : null;
     // Raw session id here too: each event is admitted on its own scope, same as recall and the CLI.
-    const recentSessionEvents = hasLocal && rawActiveSnapshot?.session_id
+    const recentSessionEvents = hasLocalTaskState && rawActiveSnapshot?.session_id
         ? listSessionEvents(ctx.hippoRoot, ctx.tenantId, {
             session_id: rawActiveSnapshot.session_id,
             limit: 5,
         }).filter((e) => passesScopeFilterForRecall(rowScope(e), undefined))
         : [];
+    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 : [];
+    const transcriptHandoffSession = shownHandoff?.evidence?.derivedFrom === 'transcript' ? shownHandoff.sessionId : null;
+    let digestHiddenForHandoff = false;
+    const ambientAdmit = (e) => {
+        // A printed handoff already carries the session's closing message, which its digest would print a second time.
+        if (transcriptHandoffSession !== null && e.source_session_id === transcriptHandoffSession && isSessionDigestRow(e)) {
+            digestHiddenForHandoff = true;
+            return false;
+        }
+        return ambientAdmitEntry(e, currentProjectName, includeCrossProject);
+    };
+    const ownSessionId = opts.currentSessionId || '';
+    // Inside admit, not after the load, so the loader's window widens past a session's own items.
+    const isOwnCompactionItem = (e) => ownSessionId !== '' &&
+        e.source_session_id === ownSessionId &&
+        e.tags.includes(COMPACTION_MEMORY_TAG);
+    // Superseded rows never inject; which rows reach ambientAdmitEntry matters because it regex-scans content for secrets.
+    const admit = (e) => !e.superseded_by && !isOwnCompactionItem(e) && ambientAdmit(e);
+    // Tenant-scoped loads (v1.11.1 lesson: NEVER resolveTenantId({}) here).
+    const localLoad = hasLocal
+        ? loadAmbientEntries(ctx.hippoRoot, ctx.tenantId, pinnedOnly, includeRecent, admit, recallRequest)
+        : { entries: [] };
+    const globalLoad = hasGlobal && !primaryIsGlobal
+        ? loadAmbientEntries(globalRoot, ctx.tenantId, pinnedOnly, includeRecent, admit, recallRequest)
+        : { entries: [] };
+    let localEntries = localLoad.entries;
+    let globalEntries = globalLoad.entries;
+    // Computed after markRetrieved runs, so avgStrength reflects post-retrieval strengths.
+    let ambientState;
     if (!promptRecallPending &&
         localEntries.length === 0 &&
         globalEntries.length === 0 &&
-        !activeSnapshot &&
-        !sessionHandoff &&
-        recentSessionEvents.length === 0) {
+        !shownSnapshot &&
+        !shownHandoff &&
+        shownEvents.length === 0) {
         return { entries: [], tokens: 0 };
     }
     let selectedItems = [];
@@ -1637,8 +1670,8 @@ export async function getContext(ctx, opts = {}) {
         if (!pinnedCfg.pinnedInject.enabled) {
             return { entries: [], tokens: 0 };
         }
-        // Effective budget: explicit opts.budget wins over config.
-        const effBudget = opts.budget !== undefined ? budget : pinnedCfg.pinnedInject.budget;
+        // 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)
         const [localPool, globalPool] = oneCopyPerMemory(localEntries, globalEntries, nowP);
         const selectedIds = new Set();
@@ -1649,7 +1682,7 @@ export async function getContext(ctx, opts = {}) {
         const pinnedLocal = localPool.filter((e) => e.pinned);
         const pinnedGlobal = globalPool.filter((e) => e.pinned);
         const rankedPinned = [
-            ...pinnedLocal.map((e) => ({ entry: e, isGlobal: false })),
+            ...pinnedLocal.map((e) => ({ entry: e, isGlobal: primaryIsGlobal })),
             ...pinnedGlobal.map((e) => ({ entry: e, isGlobal: true })),
         ]
             .map(({ entry, isGlobal }) => {
@@ -1658,7 +1691,7 @@ export async function getContext(ctx, opts = {}) {
             return {
                 entry,
                 score: calculateStrength(entry, nowP) * (isGlobal ? 1 / 1.2 : 1) * sBst,
-                tokens: estimateTokens(entry.content),
+                tokens: price(entry, isGlobal),
                 isGlobal,
             };
         })
@@ -1715,7 +1748,7 @@ export async function getContext(ctx, opts = {}) {
                     if (seenCandidateIds.has(e.id))
                         continue;
                     seenCandidateIds.add(e.id);
-                    candidateItems.push({ id: e.id, tokens: contentTokens(e.content), entry: e, isGlobal: false });
+                    candidateItems.push({ id: e.id, tokens: contentTokens(e.content), entry: e, isGlobal: primaryIsGlobal });
                 }
                 for (const e of globalCandidates) {
                     if (seenCandidateIds.has(e.id))
@@ -1727,7 +1760,7 @@ export async function getContext(ctx, opts = {}) {
                 for (const g of gated) {
                     if (selectedIds.has(g.item.id))
                         continue;
-                    const tokens = estimateTokens(g.item.entry.content);
+                    const tokens = price(g.item.entry, g.item.isGlobal, true);
                     if (usedP + tokens > recentBudget)
                         continue;
                     selectedItems.push({ entry: g.item.entry, score: g.score, tokens, isGlobal: g.item.isGlobal, promptRecall: true });
@@ -1738,7 +1771,7 @@ export async function getContext(ctx, opts = {}) {
         }
         else if (includeRecent > 0) {
             const recent = [
-                ...localPool.map((entry) => ({ entry, isGlobal: false })),
+                ...localPool.map((entry) => ({ entry, isGlobal: primaryIsGlobal })),
                 ...globalPool.map((entry) => ({ entry, isGlobal: true })),
             ]
                 // T2 (src/compare.ts) note: this already carries an explicit
@@ -1775,7 +1808,7 @@ export async function getContext(ctx, opts = {}) {
                 .map(({ entry, isGlobal }) => ({
                 entry,
                 score: calculateStrength(entry, nowP) * (isGlobal ? 1 / 1.2 : 1),
-                tokens: estimateTokens(entry.content),
+                tokens: price(entry, isGlobal),
                 isGlobal,
             }));
             for (const r of recent) {
@@ -1790,7 +1823,8 @@ export async function getContext(ctx, opts = {}) {
         }
         if (pinnedLocal.length === 0 &&
             pinnedGlobal.length === 0 &&
-            selectedItems.length === 0) {
+            selectedItems.length === 0 &&
+            !digestHiddenForHandoff) {
             return { entries: [], tokens: 0 };
         }
         for (const r of rankedPinned) {
@@ -1812,22 +1846,22 @@ export async function getContext(ctx, opts = {}) {
             .map((e) => ({
             entry: e,
             score: calculateStrength(e, now),
-            tokens: estimateTokens(e.content),
-            isGlobal: false,
+            tokens: price(e, primaryIsGlobal),
+            isGlobal: primaryIsGlobal,
         }))
             .sort(compareScoredResults);
         const globalRanked = globalPool
             .map((e) => ({
             entry: e,
             score: calculateStrength(e, now) * (1 / 1.2),
-            tokens: estimateTokens(e.content),
+            tokens: price(e, true),
             isGlobal: true,
         }))
             .sort(compareScoredResults);
         const combined = [...localRanked, ...globalRanked].sort(compareScoredResults);
         let used = 0;
         for (const r of combined) {
-            if (used + r.tokens > budget)
+            if (used + r.tokens > left)
                 continue;
             selectedItems.push(r);
             used += r.tokens;
@@ -1837,7 +1871,8 @@ export async function getContext(ctx, opts = {}) {
     else {
         // Real query: hybrid search (global + local) or physics+hybrid (local only).
         let results;
-        if (hasGlobal) {
+        const minResults = cost ? 0 : undefined; // a priced block skips an oversize top hit too, so the budget bounds it
+        if (hasGlobal && !primaryIsGlobal) {
             // searchBothHybrid loads from the store roots itself, so the ambient
             // filter above never saw its candidates. Admission runs INSIDE the
             // search via the opt-in entryFilter, BEFORE ranking, cross-store
@@ -1845,40 +1880,48 @@ export async function getContext(ctx, opts = {}) {
             // excluded row saturate the budget (codex rounds 1+3) or shadow its
             // admitted duplicate in the dedupe pass (codex round 4). Recall paths
             // never set entryFilter, so their behavior is unchanged.
+            const localIndex = loadIndex(ctx.hippoRoot);
+            const isGlobalHit = (e) => !localIndex.entries[e.id];
             const merged = await searchBothHybrid(query, ctx.hippoRoot, globalRoot, {
-                budget,
+                budget: left,
+                minResults,
+                cost: cost && ((r) => price(r.entry, isGlobalHit(r.entry))),
                 scope: activeScope,
                 tenantId: ctx.tenantId,
                 entryFilter: ambientAdmit,
             });
-            const localIndex = loadIndex(ctx.hippoRoot);
             results = merged.map((r) => ({
                 entry: r.entry,
                 score: r.score,
-                tokens: r.tokens,
-                isGlobal: !localIndex.entries[r.entry.id],
+                tokens: price(r.entry, isGlobalHit(r.entry)),
+                isGlobal: isGlobalHit(r.entry),
             }));
         }
         else {
             const ctxConfig = loadConfig(ctx.hippoRoot);
             const usePhysicsCtx = ctxConfig.physics?.enabled !== false;
+            const localCost = cost && ((r) => price(r.entry, primaryIsGlobal));
             const ctxResults = usePhysicsCtx
                 ? await physicsSearch(query, localEntries, {
-                    budget,
+                    budget: left,
+                    minResults,
+                    cost: localCost,
                     hippoRoot: ctx.hippoRoot,
                     physicsConfig: ctxConfig.physics,
                     scope: activeScope,
                 })
                 : await hybridSearch(query, localEntries, {
-                    budget,
+                    budget: left,
+                    minResults,
+                    cost: localCost,
                     hippoRoot: ctx.hippoRoot,
                     scope: activeScope,
                 });
             results = ctxResults.map((r) => ({
                 entry: r.entry,
                 score: r.score,
-                tokens: r.tokens,
-                isGlobal: false,
+                tokens: price(r.entry, primaryIsGlobal),
+                isGlobal: primaryIsGlobal,
             }));
         }
         selectedItems = results;
@@ -1905,7 +1948,7 @@ export async function getContext(ctx, opts = {}) {
                 closeHippoDb(localDb);
             }
         }
-        if (hasGlobal) {
+        if (hasGlobal && !primaryIsGlobal) {
             const globalDb = openHippoDb(globalRoot);
             try {
                 appendAuditEvent(globalDb, {
@@ -1922,8 +1965,9 @@ export async function getContext(ctx, opts = {}) {
     }
     if (limit < selectedItems.length) {
         selectedItems = selectedItems.slice(0, limit);
-        totalTokens = selectedItems.reduce((sum, r) => sum + r.tokens, 0);
     }
+    selectedItems = dropHeldCopies(selectedItems, (r) => r.entry); // after the last cut, so a merged row that was cut hides nothing
+    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.
     selectedItems = selectedItems.map((r) => ({
@@ -1932,9 +1976,9 @@ export async function getContext(ctx, opts = {}) {
         category: classifyOriginProject(r.entry.origin_project, currentProjectName),
     }));
     if (selectedItems.length === 0 &&
-        !activeSnapshot &&
-        !sessionHandoff &&
-        recentSessionEvents.length === 0) {
+        !shownSnapshot &&
+        !shownHandoff &&
+        shownEvents.length === 0) {
         // LC1 F5 fix: this bare early-return used to skip tracing entirely — a
         // query that found nothing is exactly the coverage-gap signal Track LC
         // needs. Write an empty trace (result_count 0, no result rows) so it
@@ -2013,9 +2057,9 @@ export async function getContext(ctx, opts = {}) {
     return {
         entries: selectedItems,
         tokens: totalTokens,
-        activeSnapshot: activeSnapshot ?? undefined,
-        sessionHandoff: sessionHandoff ?? undefined,
-        recentEvents: recentSessionEvents.length > 0 ? recentSessionEvents : undefined,
+        activeSnapshot: shownSnapshot ?? undefined,
+        sessionHandoff: shownHandoff ?? undefined,
+        recentEvents: shownEvents.length > 0 ? shownEvents : undefined,
         ambientState,
     };
 }
@@ -2047,8 +2091,8 @@ export function recordTokens(ctx, surface, use) {
 }
 /**
  * Token ledger totals for the tenant over the last `days` days (default 30):
- * tokens sent per surface, blocks skipped as unchanged and the tokens that
- * saved, and mean tokens per session.
+ * tokens sent, skipped as unchanged and re-read by later model calls, per
+ * surface, with session counts and mean tokens per session.
  */
 export function tokenSummary(ctx, opts = {}) {
     const db = openHippoDb(ctx.hippoRoot);

package/dist/audit.d.ts

@@ -17,7 +17,8 @@ export declare const STOP_WORDS: Set<string>;
 export declare function auditMemory(entry: MemoryEntry): AuditIssue | null;
 export declare function auditMemories(entries: MemoryEntry[]): AuditResult;
 export declare function isContentWorthStoring(content: string): boolean;
-export type AuditOp = 'remember' | 'recall' | 'promote' | 'supersede' | 'forget' | 'archive_raw' | 'auth_revoke' | 'auth_create' | 'outcome' | 'consolidate' | 'audit_prune' | 'summary_marked_dirty' | 'summary_marked_clean' | 'summary_rebuilt' | 'predict_create' | 'predict_close' | 'predict_baserate' | 'recall_autodebias_hint' | 'recall_autodebias_hint_no_class_match' | 'recall_autodebias_hint_tiebreak' | 'recall_anchor_detected_query_repeat' | 'recall_anchor_detected_memory_dominance' | 'recall_anchor_skipped_no_session' | 'recall_availability_detected' | 'decision_create' | 'decision_supersede' | 'decision_close' | 'incident_open' | 'incident_resolve' | 'incident_close' | 'process_create' | 'process_supersede' | 'process_close' | 'policy_create' | 'policy_supersede' | 'policy_close' | 'skill_create' | 'skill_supersede' | 'skill_close' | 'project_brief_create' | 'project_brief_supersede' | 'project_brief_close' | 'customer_note_create' | 'customer_note_supersede' | 'customer_note_close' | 'mv_rescue' | 'reject_value' | 'reject_refusal' | 'unreject_value' | 'half_life_migrate' | 'dormant_restore' | 'conflict_resolve' | 'auth_grant' | 'auth_ungrant' | 'quarantine' | 'quarantine_approve' | 'quarantine_reject';
+export declare const AUDIT_OPS: readonly ["remember", "recall", "promote", "supersede", "forget", "archive_raw", "auth_revoke", "auth_create", "outcome", "consolidate", "audit_prune", "summary_marked_dirty", "summary_marked_clean", "summary_rebuilt", "predict_create", "predict_close", "predict_baserate", "recall_autodebias_hint", "recall_autodebias_hint_no_class_match", "recall_autodebias_hint_tiebreak", "recall_anchor_detected_query_repeat", "recall_anchor_detected_memory_dominance", "recall_anchor_skipped_no_session", "recall_availability_detected", "decision_create", "decision_supersede", "decision_close", "incident_open", "incident_resolve", "incident_close", "process_create", "process_supersede", "process_close", "policy_create", "policy_supersede", "policy_close", "skill_create", "skill_supersede", "skill_close", "project_brief_create", "project_brief_supersede", "project_brief_close", "customer_note_create", "customer_note_supersede", "customer_note_close", "mv_rescue", "reject_value", "reject_refusal", "unreject_value", "conflict_resolve", "half_life_migrate", "dormant_restore", "auth_grant", "auth_ungrant", "quarantine", "quarantine_approve", "quarantine_reject", "agent_memory_restore", "agent_memory_set_aside"];
+export type AuditOp = (typeof AUDIT_OPS)[number];
 export interface AppendAuditOpts {
     tenantId: string;
     actor: string;

package/dist/audit.js

@@ -111,9 +111,10 @@ function hasNoSpecificity(text) {
 }
 export function auditMemory(entry) {
     const issue = classifyMemory(entry);
-    // Error means "auto-remove"; a pinned or raw row is never auto-removed, so it can only warn.
+    // Error means "auto-remove"; a pinned, raw or kept-for-good row is never auto-removed, so it can only warn.
     if (issue?.severity === 'error' && !canAutoDelete(entry)) {
-        return { ...issue, severity: 'warning', reason: `${issue.reason} (${entry.pinned ? 'pinned' : 'raw'}, kept)` };
+        const why = entry.pinned ? 'pinned' : entry.kind === 'raw' ? 'raw' : 'keep rule';
+        return { ...issue, severity: 'warning', reason: `${issue.reason} (${why}, kept)` };
     }
     return issue;
 }
@@ -167,6 +168,71 @@ export function isContentWorthStoring(content) {
         return false;
     return true;
 }
+// ---------------------------------------------------------------------------
+// A5 audit log primitives (append-only mutation trail)
+// ---------------------------------------------------------------------------
+// The one list of audit ops: the AuditOp type, `hippo audit list --op` and GET /v1/audit?op= all read it.
+export const AUDIT_OPS = [
+    'remember',
+    'recall',
+    'promote',
+    'supersede',
+    'forget',
+    'archive_raw',
+    'auth_revoke',
+    'auth_create', // emitted by api.authCreate
+    'outcome',
+    'consolidate', // emitted once per api.sleep invocation
+    'audit_prune', // emitted by pruneAuditLog after each retention prune
+    'summary_marked_dirty', // emitted by markSummaryDirty on the 0->1 transition
+    'summary_marked_clean', // emitted by clearSummaryDirtyAfterBuild after the buildDag child-link loop
+    'summary_rebuilt', // emitted by applyRebuildResult on a successful sleep-cycle rebuild
+    'predict_create', // emitted by savePrediction
+    'predict_close', // emitted by closePrediction
+    'predict_baserate', // emitted by computePredictionBaserate
+    'recall_autodebias_hint', // emitted by computePlanningFallacyOutput on success
+    'recall_autodebias_hint_no_class_match', // telemetry: forward-claim detected, no class scored
+    'recall_autodebias_hint_tiebreak', // telemetry: forward-claim detected, two or more classes tied
+    'recall_anchor_detected_query_repeat', // emitted by the anchoring detector when the same query returns the same top-1
+    'recall_anchor_detected_memory_dominance', // emitted by the anchoring detector when one memory wins top-1 across distinct queries
+    'recall_anchor_skipped_no_session', // telemetry: no sessionId, so ring tracking was skipped
+    'recall_availability_detected', // emitted when the availability/recency-bias hint fires
+    'decision_create', // emitted by saveDecision
+    'decision_supersede', // emitted by saveDecision when --supersedes resolves to an active decision
+    'decision_close', // emitted by closeDecision
+    'incident_open', // emitted by saveIncident
+    'incident_resolve', // emitted by resolveIncident
+    'incident_close', // emitted by closeIncident
+    'process_create', // emitted by saveProcess
+    'process_supersede', // emitted by saveProcess on a supersession
+    'process_close', // emitted by closeProcess
+    'policy_create', // emitted by savePolicy
+    'policy_supersede', // emitted by savePolicy on a supersession
+    'policy_close', // emitted by closePolicy
+    'skill_create', // emitted by saveSkill
+    'skill_supersede', // emitted by saveSkill on a supersession
+    'skill_close', // emitted by closeSkill
+    'project_brief_create', // emitted by saveProjectBrief
+    'project_brief_supersede', // emitted by saveProjectBrief on a supersession, including a refresh
+    'project_brief_close', // emitted by closeProjectBrief
+    'customer_note_create', // emitted by saveCustomerNote
+    'customer_note_supersede', // emitted by saveCustomerNote on a supersession
+    'customer_note_close', // emitted by closeCustomerNote
+    'mv_rescue', // emitted by consolidate() per rescued entry when config.memoryValue.enabled
+    'reject_value', // emitted by the `hippo reject` verb
+    'reject_refusal', // emitted when the rejection guard refuses a write
+    'unreject_value', // emitted by the `hippo unreject` verb
+    'conflict_resolve', // emitted by resolveConflict on every resolution path
+    'half_life_migrate', // emitted by migrateDefaultHalfLife with the rescaled ids
+    'dormant_restore', // emitted by api.restoreDormant
+    'auth_grant', // emitted by api.authGrant
+    'auth_ungrant', // emitted by api.authUngrant
+    'quarantine', // emitted by recordQuarantine inside remember's write transaction
+    'quarantine_approve', // emitted by api.quarantineApprove
+    'quarantine_reject', // emitted by api.quarantineReject
+    'agent_memory_restore', // emitted by the agent memory sync when a deleted note comes back
+    'agent_memory_set_aside', // emitted by the agent memory sync when a note is deleted or refused
+];
 function isBigIntValue(value) {
     return typeof value === 'bigint';
 }