hippo-memory 1.52.8 → 1.52.9

package/dist/api.d.ts

@@ -274,6 +274,9 @@ export interface RecallOpts {
      * callers leave this unset and get the trace.
      */
     suppressRecallTrace?: boolean;
+    /** Set only by the MCP recall tool, which ranks with its own scorer and drops copies from its own final list: this call
+     *  then keeps a memory that a merged row in the same result holds word for word. Other callers leave it unset. */
+    keepHeldCopies?: boolean;
 }
 export interface ContinuityBlock {
     activeSnapshot: TaskSnapshot | null;
@@ -373,7 +376,7 @@ export interface RecallResult {
      * the calling agent sees its track record at the moment of forecasting
      * (Lovallo-Kahneman 2003 inside-vs-outside view).
      *
-     * Populated by `api.recall` itself via `computePlanningFallacyHint`.
+     * Populated by `api.recall` itself via `computePlanningFallacyOutput`.
      * Pipeline-invariant: the value depends only on (queryText, tenantId,
      * predictions table state) — all three are identical regardless of
      * which downstream search pipeline produces the memory list, so MCP
@@ -553,6 +556,11 @@ export interface AssembleOpts {
      * is set on the result so the caller knows to widen.
      */
     rowCap?: number;
+    cost?: AssembleCost;
+}
+export interface AssembleCost {
+    item: (it: AssembledContextItem) => number;
+    fixed: (widest: number) => number;
 }
 export interface AssembledContextItem {
     id: string;
@@ -623,7 +631,7 @@ export interface DrillDownOpts {
     /**
      * Optional token budget. When set, children are appended in chronological
      * order (created ASC) until adding the next child would exceed the budget.
-     * Token cost = ceil(content.length / 4) per child.
+     * Token cost = the child's printed line under `cost`, else ceil(content.length / 4).
      *
      * For depth > 1, the budget is GLOBAL cumulative (NOT per-level).
      */
@@ -636,22 +644,29 @@ export interface DrillDownOpts {
      * construction).
      */
     depth?: number;
+    cost?: DrillDownCost;
+}
+export interface DrillDownSummary {
+    id: string;
+    content: string;
+    descendantCount: number;
+    earliestAt: string | null;
+    latestAt: string | null;
+}
+export interface DrillDownChild {
+    id: string;
+    content: string;
+    layer: string;
+    dagLevel: number;
+    created: string;
+}
+export interface DrillDownCost {
+    child: (c: DrillDownChild) => number;
+    fixed: (summary: DrillDownSummary, widest: number) => number;
 }
 export interface DrillDownResult {
-    summary: {
-        id: string;
-        content: string;
-        descendantCount: number;
-        earliestAt: string | null;
-        latestAt: string | null;
-    };
-    children: Array<{
-        id: string;
-        content: string;
-        layer: string;
-        dagLevel: number;
-        created: string;
-    }>;
+    summary: DrillDownSummary;
+    children: DrillDownChild[];
     totalChildren: number;
     truncated: boolean;
 }
@@ -955,10 +970,28 @@ export interface ContextOpts {
     currentSessionId?: string | null;
     /** Z1: raw hook-payload prompt; only the pinned-only branch reads it, gated on `pinnedInject.promptRecall`. */
     prompt?: string;
+    /** What the budget pays for, from the caller that renders the block. Absent = the memory text alone. */
+    cost?: ContextCost;
+}
+/** Budget prices in the text a caller prints, so the budget bounds what reaches the model. */
+export interface ContextCost {
+    /** Tokens of one entry as printed. */
+    entry: (item: Pick<ContextResultEntry, 'entry' | 'isGlobal' | 'promptRecall' | 'origin' | 'category'>) => number;
+    /** Tokens of the headers and footer the block can print at this budget, reserved before any entry. */
+    fixed: (budget: number, can: {
+        cross: boolean;
+        promptRecall: boolean;
+        ambient: boolean;
+    }) => number;
+    /** Tokens of the sections printed ahead of the memories, each as printed. */
+    snapshot: (s: TaskSnapshot) => number;
+    handoff: (h: SessionHandoff) => number;
+    trail: (events: SessionEvent[]) => number;
 }
 export interface ContextResultEntry {
     entry: MemoryEntry;
     score: number;
+    /** What this entry cost the budget: its printed line under `ContextOpts.cost`, else its memory text. */
     tokens: number;
     isGlobal?: boolean;
     isFreshTail?: boolean;
@@ -1037,8 +1070,8 @@ export declare function recordTokens(ctx: Context, surface: TokenSurface, use: {
 }): void;
 /**
  * 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 declare function tokenSummary(ctx: Context, opts?: {
     days?: number;

package/dist/api.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.
@@ -1557,11 +1567,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 +1576,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
@@ -1621,12 +1629,38 @@ export async function getContext(ctx, opts = {}) {
             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);
+    };
+    // Superseded rows never inject; which rows reach ambientAdmitEntry matters because it regex-scans content for secrets.
+    const admit = (e) => !e.superseded_by && 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
+        ? loadAmbientEntries(globalRoot, ctx.tenantId, pinnedOnly, includeRecent, admit, !isGlobalStoreRoot(ctx.hippoRoot) ? recallRequest : undefined)
+        : { 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 +1671,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();
@@ -1658,7 +1692,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,
             };
         })
@@ -1727,7 +1761,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 });
@@ -1775,7 +1809,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 +1824,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,7 +1847,7 @@ export async function getContext(ctx, opts = {}) {
             .map((e) => ({
             entry: e,
             score: calculateStrength(e, now),
-            tokens: estimateTokens(e.content),
+            tokens: price(e, false),
             isGlobal: false,
         }))
             .sort(compareScoredResults);
@@ -1820,14 +1855,14 @@ export async function getContext(ctx, opts = {}) {
             .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,6 +1872,7 @@ export async function getContext(ctx, opts = {}) {
     else {
         // Real query: hybrid search (global + local) or physics+hybrid (local only).
         let results;
+        const minResults = cost ? 0 : undefined; // a priced block skips an oversize top hit too, so the budget bounds it
         if (hasGlobal) {
             // searchBothHybrid loads from the store roots itself, so the ambient
             // filter above never saw its candidates. Admission runs INSIDE the
@@ -1845,39 +1881,47 @@ 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, false));
             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,
+                tokens: price(r.entry, false),
                 isGlobal: false,
             }));
         }
@@ -1922,8 +1966,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 +1977,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 +2058,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 +2092,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"];
+export type AuditOp = (typeof AUDIT_OPS)[number];
 export interface AppendAuditOpts {
     tenantId: string;
     actor: string;

package/dist/audit.js

@@ -167,6 +167,69 @@ 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
+];
 function isBigIntValue(value) {
     return typeof value === 'bigint';
 }