hippo-memory 1.52.8 → 1.53.0

package/dist/mcp/server.js

@@ -16,7 +16,8 @@ import { loadAllEntries, writeEntry, strengthenRetrieved, readEntry, loadFreshAc
 import { shareMemory, listPeers, getGlobalRoot, initGlobal } from '../shared.js';
 import { consolidate } from '../consolidate.js';
 import { execSync } from 'child_process';
-import { fetchGitLog, extractLessons, partitionLessons, deduplicateLesson, isGitRepo } from '../autolearn.js';
+import { fetchGitLog, extractLessons, partitionLessons, isGitRepo } from '../autolearn.js';
+import { dropHeldCopies, duplicateKey, storedTextKeys } from '../same-text.js';
 import { loadConfig } from '../config.js';
 import { confidenceLabel } from '../memory.js';
 import { resolveTenantId } from '../tenant.js';
@@ -74,6 +75,7 @@ function isJsonObjectRecord(v) {
     return v !== undefined && v !== null && typeof v === 'object' && !Array.isArray(v);
 }
 import { formatHandoffEvidenceLine } from '../handoff.js';
+import { assembleCost, assembleText, drillCost, drillText, printedTokens } from '../context-render.js';
 function formatContinuityBlock(block) {
     const lines = ['## Continuity'];
     if (block.activeSnapshot) {
@@ -123,19 +125,54 @@ function formatContinuityBlock(block) {
     }
     return lines.join('\n');
 }
-function formatMemories(results, hippoRoot) {
+const NO_MEMORIES = 'No relevant memories found.';
+function memoriesHeading(count) {
+    return `Found ${count} memories:\n`;
+}
+function formatMemory(r) {
+    const conf = confidenceLabel(r.entry).text;
+    const tags = r.entry.tags.length > 0 ? ` tags: ${r.entry.tags.join(', ')}` : '';
+    return `[${conf}]${tags} (strength=${r.entry.strength.toFixed(2)})\n${r.entry.content}\n`;
+}
+function formatMemories(results) {
     if (results.length === 0)
-        return 'No relevant memories found.';
-    const config = loadConfig(hippoRoot);
-    const lines = [`Found ${results.length} memories:\n`];
-    for (const r of results) {
-        const conf = confidenceLabel(r.entry).text;
-        const tags = r.entry.tags.length > 0 ? ` tags: ${r.entry.tags.join(', ')}` : '';
-        lines.push(`[${conf}]${tags} (strength=${r.entry.strength.toFixed(2)})`);
-        lines.push(r.entry.content);
-        lines.push('');
+        return NO_MEMORIES;
+    return [memoriesHeading(results.length), ...results.map(formatMemory)].join('\n');
+}
+/** What a memory costs the budget: the text formatMemories prints for it. */
+const memoryCost = (r) => printedTokens(formatMemory(r));
+// The widest heading or the empty-list line, whichever costs more, so either prints inside the budget.
+function memoriesReserve(budget) {
+    return Math.max(printedTokens(memoriesHeading(budget)), estimateTokens(NO_MEMORIES));
+}
+// Rows the ranked list already shows drop out of this section, so pricing every row bounds what it prints.
+function tailSection(rows) {
+    if (rows.length === 0)
+        return '';
+    const lines = ['', '## Fresh tail / substituted summaries'];
+    for (const r of rows) {
+        const tag = r.isSummary ? '[summary]' : '[tail]';
+        const head = r.content.length > 200 ? r.content.slice(0, 200) + '…' : r.content;
+        if (r.isSummary && r.substitutedFor && r.substitutedFor.length > 0) {
+            lines.push(`- ${tag} ${r.id} (covers ${r.substitutedFor.length} rows): ${head}`);
+        }
+        else {
+            lines.push(`- ${tag} ${r.id}: ${head}`);
+        }
     }
-    return lines.join('\n');
+    return '\n' + lines.join('\n');
+}
+// J3.2: the hint depends on the query alone, so api.recall's copy is the one shown; JSON.stringify fences the phrase.
+function planningSection(r) {
+    if (r.planningFallacyHint) {
+        const h = r.planningFallacyHint;
+        return `## Planning fallacy hint\nClass: ${h.classTag}\n${h.baserateSummary}\n(detected: ${JSON.stringify(h.detectedPhrase)})\n\n---\n\n`;
+    }
+    if (r.planningFallacyWatching) {
+        const w = r.planningFallacyWatching;
+        return `## Planning fallacy watch\nReason: ${w.reason}\n${w.suggestion}\n(detected: ${JSON.stringify(w.detectedPhrase)})\n\n---\n\n`;
+    }
+    return '';
 }
 // ── Tool definitions ──
 const TOOLS = [
@@ -512,6 +549,7 @@ async function executeTool(name, args, ctx) {
                 // never actually saw. Real MCP tracing is the reserved 'mcp'
                 // pipeline value (schema v40) — a follow-up, not v1 scope.
                 suppressRecallTrace: true,
+                keepHeldCopies: true,
                 ...recallExtra,
             });
             // Existing physics/hybrid scorer continues to drive user-visible
@@ -532,10 +570,26 @@ async function executeTool(name, args, ctx) {
                 ? allEntries.filter((e) => e.scope === explicitScope)
                 : allEntries.filter((e) => passesScopeFilterForRecall(e.scope ?? null, undefined));
             const droppedPreRankCountMcp = allEntries.length - entries.length;
+            // Sections are paid in print order, ahead of the memories and after the heading; one that does not fit is dropped whole.
+            let left = budget - memoriesReserve(budget);
+            const pays = (piece) => {
+                const tokens = estimateTokens(piece);
+                if (tokens > left)
+                    return false;
+                left -= tokens;
+                return true;
+            };
+            const planPiece = planningSection(apiResult);
+            const showPlan = planPiece !== '' && pays(planPiece);
+            const tailRows = apiResult.results.filter((r) => r.isFreshTail || r.isSummary);
+            const showTail = tailRows.length > 0 && pays(tailSection(tailRows));
+            const continuityPiece = includeContinuity && apiResult.continuity ? `\n\n${formatContinuityBlock(apiResult.continuity)}` : '';
+            const showContinuity = continuityPiece !== '' && pays(continuityPiece);
             const usePhysics = config.physics?.enabled !== false;
+            const fit = { budget: Math.max(0, left), cost: memoryCost, hippoRoot };
             let results = usePhysics
-                ? await physicsSearch(query, entries, { budget, hippoRoot, physicsConfig: config.physics })
-                : await hybridSearch(query, entries, { budget, hippoRoot });
+                ? await physicsSearch(query, entries, { ...fit, physicsConfig: config.physics })
+                : await hybridSearch(query, entries, fit);
             // v1.12.13 / C5 — droppedByBudget for MCP is an UPPER BOUND. The
             // difference (entries.length - results.length) lumps three things
             // together: rows hybridSearch/physicsSearch internally dropped because
@@ -553,7 +607,7 @@ async function executeTool(name, args, ctx) {
             // compute droppedByBudget = scoredCount - results.length, with the
             // remainder (entries.length - scoredCount) attributed to
             // droppedPreRank or a new "noQueryMatch" counter.
-            const droppedByBudgetCountMcp = Math.max(0, entries.length - results.length);
+            const droppedByBudgetFor = (shown) => Math.max(0, entries.length - shown);
             // v1.7.4 -- dlPFC goal-stack boost on the MCP physics/hybrid result
             // list BEFORE formatMemories. MCP's user-visible primary ordering does
             // NOT come from api.recall (apiResult above), so the boost has to run
@@ -572,26 +626,71 @@ async function executeTool(name, args, ctx) {
                     closeHippoDb(dbForBoost);
                 }
             }
-            const retrievedIds = results.map((r) => r.entry.id);
+            // J1, J2 and C5: MCP ranks its own list (its top-1 can differ from api.recall's), so its hints and Cutoff block are its own.
+            const anchorRing = process.env.HIPPO_ANCHORING !== 'off' && sessionId
+                ? getOrCreateRing(sessionRecallHistoryMcp, buildSessionKey(tenantId, sessionId))
+                : null;
+            const queryHash = hashQueryText(query);
+            const render = (cut) => {
+                const list = dropHeldCopies(cut, (r) => r.entry); // after every cut, so a merged row cut here never hides its sources
+                const anchoring = anchorRing ? detectAnchoring(snapshotRing(anchorRing), queryHash, list[0]?.entry.id ?? null) : null;
+                const availability = process.env.HIPPO_AVAILABILITY !== 'off'
+                    ? detectAvailabilityBias({
+                        topK: list.map((r) => ({ id: r.entry.id, created: r.entry.created })),
+                        pool: entries.map((e) => ({ id: e.id, created: e.created })),
+                    })
+                    : null;
+                const shownIds = new Set(list.map((r) => r.entry.id));
+                const shownKeys = storedTextKeys(list.map((r) => r.entry));
+                const tail = showTail
+                    ? dropHeldCopies(tailRows.filter((r) => !shownIds.has(r.id) && !shownKeys.has(duplicateKey(r.content))), (r) => r)
+                    : [];
+                const s = buildSuppressionSummary({
+                    totalCandidates: totalCandidatesCountMcp,
+                    droppedPreRank: droppedPreRankCountMcp + cut.length - list.length, // the bucket CLI and API recall put hidden copies in
+                    droppedByBudget: droppedByBudgetFor(cut.length),
+                    summarySubstitutionsAdded: tail.filter((r) => r.isSummary).length,
+                    freshTailAdded: tail.filter((r) => r.isFreshTail && !r.isSummary).length,
+                    suppressedByInterference: anchoring?.reason === 'memory_dominance' ? 1 : 0,
+                });
+                // Anchoring is the stronger pull, so it prints first; the Cutoff block sits above the list, where the agent reads it.
+                let text = anchoring ? `## Anchoring hint\n${anchoring.summary}\n[anchored_on: ${anchoring.memoryId}]\n\n---\n\n` : '';
+                if (availability)
+                    text += `## Availability bias\n${availability.summary}\n\n---\n\n`;
+                if (showPlan)
+                    text += planPiece;
+                const cutoffClauses = [];
+                if (s.droppedByBudget > 0)
+                    cutoffClauses.push(`${s.droppedByBudget} dropped to fit limit`);
+                if (s.droppedPreRank > 0)
+                    cutoffClauses.push(`${s.droppedPreRank} filtered pre-rank`);
+                if (s.summarySubstitutionsAdded > 0)
+                    cutoffClauses.push(`${s.summarySubstitutionsAdded} summary substitutions added`);
+                if (s.freshTailAdded > 0)
+                    cutoffClauses.push(`${s.freshTailAdded} fresh-tail added`);
+                if (s.suppressedByInterference > 0)
+                    cutoffClauses.push(`${s.suppressedByInterference} suppressed by interference`);
+                if (cutoffClauses.length > 0) {
+                    text += `## Cutoff\nShowing ${list.length} of ${s.totalCandidates} candidates; ${cutoffClauses.join('; ')}.\n\n---\n\n`;
+                }
+                // v1.6.3: the fresh-tail and summary rows api.recall produced follow the ranked list, or the MCP fields go unanswered.
+                text += formatMemories(list) + tailSection(tail) + (showContinuity ? continuityPiece : '');
+                return { anchoring, availability, text, list };
+            };
+            let rendered = render(results);
+            // The hints, Cutoff block and heading vary with the list, so the lowest-ranked entry goes until the whole response fits.
+            while (results.length > 1 && estimateTokens(rendered.text) > budget) {
+                results = results.slice(0, -1);
+                rendered = render(results);
+            }
+            const { anchoring: mcpAnchoringHint, availability: mcpAvailabilityHint, list: shown } = rendered;
+            const retrievedIds = shown.map((r) => r.entry.id);
             strengthenRetrieved(hippoRoot, retrievedIds);
             lastRecalledIds.set(resolveClientKey(ctx), retrievedIds);
-            // v0.33 / J1 — MCP per-pipeline anchoring detector. UNLIKE J3.2's
-            // planningFallacyHint (which is pipeline-invariant because it
-            // depends only on queryText + predictions table state), the
-            // anchoring hint depends on (a) per-pipeline top-1 ranking (MCP's
-            // physics/hybrid winner can differ from api.recall's BM25 winner)
-            // and (b) per-pipeline ring buffer. So MCP computes its OWN hint
-            // against MCP's own top-1, mirroring the C5 per-pipeline rule.
-            let mcpAnchoringHint = null;
             if (process.env.HIPPO_ANCHORING !== 'off') {
-                if (sessionId) {
-                    const ringKey = buildSessionKey(tenantId, sessionId);
-                    const ring = getOrCreateRing(sessionRecallHistoryMcp, ringKey);
-                    const queryHash = hashQueryText(query);
-                    const topId = results[0]?.entry.id ?? null;
-                    mcpAnchoringHint = detectAnchoring(snapshotRing(ring), queryHash, topId);
-                    appendRecall(ring, queryHash, topId, mcpAnchoringHint?.memoryId);
-                    // Pipeline-local audit emission (lockstep with CLI / api.recall).
+                if (anchorRing) {
+                    // Appended after the final detect: anchoredOn feeds the cooldown for the next recall on this session.
+                    appendRecall(anchorRing, queryHash, shown[0]?.entry.id ?? null, mcpAnchoringHint?.memoryId);
                     if (mcpAnchoringHint?.reason === 'memory_dominance') {
                         const dbForAudit = openHippoDb(hippoRoot);
                         try {
@@ -650,160 +749,25 @@ async function executeTool(name, args, ctx) {
                     }
                 }
             }
-            // v0.32 / J3.2 — auto-injection of reference-class baserate hint
-            // when the query carries a forward-prediction phrase. Read from
-            // apiResult.planningFallacyHint (already computed inside api.recall
-            // with the caller identity threaded through ctx.actor.subject -
-            // auth-resolved actor under HTTP-MCP, 'mcp' for stdio). The hint is
-            // pipeline-INVARIANT — same (hippoRoot, tenantId, query) inputs
-            // produce the same hint regardless of which downstream search
-            // pipeline (api.recall band vs physics/hybrid) renders the memory
-            // list, so re-computing here would double the audit emission for
-            // identical telemetry. C5 per-pipeline rule does NOT apply here
-            // because the hint depends on queryText, not on the matched memory
-            // set. Prepend BEFORE the memory list so the agent sees it first.
-            // v0.33 / J1: Anchoring hint goes ABOVE planning-fallacy hint
-            // (anchoring is the stronger cognitive-pull warning).
-            // v1.13.3 / C5 follow-up — Build MCP-pipeline suppressionSummary BEFORE
-            // the response is assembled so the Cutoff block can render at TOP
-            // alongside the other Track J hints. The dogfood
-            // (docs/dogfood/2026-05-27-track-j-warnings.md) showed the v1.13.0-v1.13.2
-            // bottom-placement was dark: a fresh sub-agent summarised the visible
-            // memories with zero mention of the dropped pool. Top-placement + plain-
-            // English rewrite fixes the read-rate without any system-prompt addendum.
-            const physicsIds = new Set(results.map((r) => r.entry.id));
-            const tailOrSummary = apiResult.results.filter((r) => (r.isFreshTail || r.isSummary) && !physicsIds.has(r.id));
-            const freshTailAddedMcp = tailOrSummary.filter((r) => r.isFreshTail && !r.isSummary).length;
-            const summarySubsAddedMcp = tailOrSummary.filter((r) => r.isSummary).length;
-            // v0.33 / J1: suppressedByInterference bumped on MCP's R2 fire.
-            const mcpSuppressedByInterference = mcpAnchoringHint?.reason === 'memory_dominance' ? 1 : 0;
-            const mcpSuppressionSummary = buildSuppressionSummary({
-                totalCandidates: totalCandidatesCountMcp,
-                droppedPreRank: droppedPreRankCountMcp,
-                droppedByBudget: droppedByBudgetCountMcp,
-                summarySubstitutionsAdded: summarySubsAddedMcp,
-                freshTailAdded: freshTailAddedMcp,
-                suppressedByInterference: mcpSuppressedByInterference,
-            });
-            // v1.13.x / J2 — MCP per-pipeline availability/recency-bias detector.
-            // Like the anchoring hint above (and unlike J3.2's pipeline-invariant
-            // planningFallacyHint), this depends on MCP's OWN returned top-K and the
-            // scope-filtered candidate pool (entries) it was drawn from, so MCP
-            // computes its own hint here. Soft warning only. Gated by
-            // HIPPO_AVAILABILITY=off; audit emission is pipeline-local (actor =
-            // auth-resolved ctx.actor under HTTP-MCP, 'mcp' for stdio).
-            let mcpAvailabilityHint = null;
-            if (process.env.HIPPO_AVAILABILITY !== 'off') {
-                mcpAvailabilityHint = detectAvailabilityBias({
-                    topK: results.map((r) => ({ id: r.entry.id, created: r.entry.created })),
-                    pool: entries.map((e) => ({ id: e.id, created: e.created })),
-                });
-                if (mcpAvailabilityHint) {
-                    const dbForAudit = openHippoDb(hippoRoot);
-                    try {
-                        appendAuditEvent(dbForAudit, {
-                            tenantId,
-                            actor: ctx?.actor ?? 'mcp',
-                            op: 'recall_availability_detected',
-                            metadata: {
-                                recent_fraction: mcpAvailabilityHint.recentFraction,
-                                older_passed_over: mcpAvailabilityHint.olderCandidatesPassedOver,
-                                returned_count: mcpAvailabilityHint.returnedCount,
-                            },
-                        });
-                    }
-                    finally {
-                        closeHippoDb(dbForAudit);
-                    }
-                }
-            }
-            let response = '';
-            if (mcpAnchoringHint) {
-                response =
-                    `## Anchoring hint\n` +
-                        `${mcpAnchoringHint.summary}\n` +
-                        `[anchored_on: ${mcpAnchoringHint.memoryId}]\n` +
-                        `\n---\n\n`;
-            }
-            // v1.13.x / J2 — availability/recency-bias hint, rendered below the
-            // anchoring hint and above the planning-fallacy hint. Soft warning only.
             if (mcpAvailabilityHint) {
-                response += `## Availability bias\n${mcpAvailabilityHint.summary}\n\n---\n\n`;
-            }
-            if (apiResult.planningFallacyHint) {
-                const h = apiResult.planningFallacyHint;
-                const safePhrase = JSON.stringify(h.detectedPhrase);
-                response +=
-                    `## Planning fallacy hint\n` +
-                        `Class: ${h.classTag}\n` +
-                        `${h.baserateSummary}\n` +
-                        `(detected: ${safePhrase})\n` +
-                        `\n---\n\n`;
-            }
-            else if (apiResult.planningFallacyWatching) {
-                // v1.13.4 / J3.2 follow-up — surface the watching variant when
-                // the regex matched but no baserate could be produced
-                // (no_class_match / tiebreak). Mutually exclusive with the hint
-                // block above. Suggestion text directs the user toward an action
-                // (typically: tag a prediction class) that would unblock the
-                // hint next time.
-                const w = apiResult.planningFallacyWatching;
-                const safePhrase = JSON.stringify(w.detectedPhrase);
-                response +=
-                    `## Planning fallacy watch\n` +
-                        `Reason: ${w.reason}\n` +
-                        `${w.suggestion}\n` +
-                        `(detected: ${safePhrase})\n` +
-                        `\n---\n\n`;
-            }
-            // v1.13.3 / C5 follow-up — Cutoff block (was "WYSIATI:" line at bottom
-            // in v1.13.0-v1.13.2). Top placement so the agent reads the cutoff
-            // before scrolling the result list. "Cutoff" is plain English; the old
-            // "WYSIATI:" acronym was opaque to agents without Kahneman context per
-            // the 2026-05-27 dogfood Trial 1.
-            const sMcp = mcpSuppressionSummary;
-            const cutoffClauses = [];
-            if (sMcp.droppedByBudget > 0)
-                cutoffClauses.push(`${sMcp.droppedByBudget} dropped to fit limit`);
-            if (sMcp.droppedPreRank > 0)
-                cutoffClauses.push(`${sMcp.droppedPreRank} filtered pre-rank`);
-            if (sMcp.summarySubstitutionsAdded > 0)
-                cutoffClauses.push(`${sMcp.summarySubstitutionsAdded} summary substitutions added`);
-            if (sMcp.freshTailAdded > 0)
-                cutoffClauses.push(`${sMcp.freshTailAdded} fresh-tail added`);
-            if (sMcp.suppressedByInterference > 0)
-                cutoffClauses.push(`${sMcp.suppressedByInterference} suppressed by interference`);
-            if (cutoffClauses.length > 0) {
-                response +=
-                    `## Cutoff\n` +
-                        `Showing ${results.length} of ${sMcp.totalCandidates} candidates; ${cutoffClauses.join('; ')}.\n` +
-                        `\n---\n\n`;
-            }
-            response += formatMemories(results, hippoRoot);
-            // v1.6.3 codex P2 fix. The physics/hybrid scorer drives the primary
-            // ranked block above, so user-visible ordering is preserved. But
-            // when the v1.5.0+/v1.5.2 RecallOpts are passed, we MUST also surface
-            // the fresh-tail and substituted-summary items apiRecall produced —
-            // otherwise the advertised MCP fields are silently ignored. Append
-            // them as their own section, deduplicated against the physics ranking.
-            if (tailOrSummary.length > 0) {
-                const lines = ['', '## Fresh tail / substituted summaries'];
-                for (const r of tailOrSummary) {
-                    const tag = r.isSummary ? '[summary]' : '[tail]';
-                    const head = r.content.length > 200 ? r.content.slice(0, 200) + '…' : r.content;
-                    if (r.isSummary && r.substitutedFor && r.substitutedFor.length > 0) {
-                        lines.push(`- ${tag} ${r.id} (covers ${r.substitutedFor.length} rows): ${head}`);
-                    }
-                    else {
-                        lines.push(`- ${tag} ${r.id}: ${head}`);
-                    }
+                const dbForAudit = openHippoDb(hippoRoot);
+                try {
+                    appendAuditEvent(dbForAudit, {
+                        tenantId,
+                        actor: ctx?.actor ?? 'mcp',
+                        op: 'recall_availability_detected',
+                        metadata: {
+                            recent_fraction: mcpAvailabilityHint.recentFraction,
+                            older_passed_over: mcpAvailabilityHint.olderCandidatesPassedOver,
+                            returned_count: mcpAvailabilityHint.returnedCount,
+                        },
+                    });
+                }
+                finally {
+                    closeHippoDb(dbForAudit);
                 }
-                response += '\n' + lines.join('\n');
-            }
-            if (includeContinuity && apiResult.continuity) {
-                response += '\n\n' + formatContinuityBlock(apiResult.continuity);
             }
-            return response;
+            return rendered.text;
         }
         case 'hippo_assemble': {
             const sessionId = String(args.session_id || '');
@@ -830,14 +794,9 @@ async function executeTool(name, args, ctx) {
             const r = apiAssemble(apiCtx, sessionId, {
                 summarizeOlder,
                 ...assembleExtra,
+                cost: assembleCost(sessionId),
             });
-            const lines = [];
-            lines.push(`Session ${r.sessionId} — ${r.items.length} items, ${r.tokens} tokens (raw=${r.totalRaw}, summarized=${r.summarized}, evicted=${r.evicted})`);
-            for (const it of r.items) {
-                const prefix = it.isSummary ? '[summary]' : it.isFreshTail ? '[tail]' : '[older]';
-                lines.push(`  ${prefix} ${it.createdAt} ${it.id} - ${it.content}`);
-            }
-            return lines.join('\n');
+            return assembleText(r);
         }
         case 'hippo_drill': {
             const summaryId = String(args.summary_id || '');
@@ -868,7 +827,7 @@ async function executeTool(name, args, ctx) {
                 drillExtra.budget = budget;
             if (depth !== undefined)
                 drillExtra.depth = depth;
-            const r = apiDrillDown(apiCtx, summaryId, { ...drillExtra });
+            const r = apiDrillDown(apiCtx, summaryId, { ...drillExtra, cost: drillCost });
             if ('failure' in r) {
                 // v1.6.4: only not_drillable is caller-actionable. not_found
                 // intentionally collapses cross-tenant + scope-blocked + missing
@@ -879,15 +838,7 @@ async function executeTool(name, args, ctx) {
                 }
                 return `No drillable summary at id=${summaryId}.`;
             }
-            const lines = [];
-            lines.push(`Summary ${r.summary.id} — ${r.summary.descendantCount} descendants${r.summary.earliestAt ? ` (${r.summary.earliestAt} -> ${r.summary.latestAt})` : ''}`);
-            lines.push(`  ${r.summary.content}`);
-            lines.push('');
-            lines.push(`Children (${r.children.length}/${r.totalChildren}${r.truncated ? ', truncated' : ''}):`);
-            for (const c of r.children) {
-                lines.push(`  [L${c.dagLevel}] ${c.id} - ${c.content}`);
-            }
-            return lines.join('\n');
+            return drillText(r);
         }
         case 'hippo_predict_baserate': {
             // J3 reference-class / planning-fallacy detector. Reads from the E2
@@ -1031,13 +982,6 @@ async function executeTool(name, args, ctx) {
                     return true;
                 return classifyOriginProject(e.origin_project, mcpProjectName) !== 'cross-project';
             });
-            const usePhysicsCtx = config.physics?.enabled !== false;
-            const results = usePhysicsCtx
-                ? await physicsSearch(query, entries, { budget, hippoRoot, physicsConfig: config.physics })
-                : await hybridSearch(query, entries, { budget, hippoRoot });
-            const retrievedIds = results.map((r) => r.entry.id);
-            strengthenRetrieved(hippoRoot, retrievedIds);
-            lastRecalledIds.set(resolveClientKey(ctx), retrievedIds);
             // DF1 (docs/plans/2026-08-23-df1-snapshot-lifecycle.md, T2): bounded
             // read, no session id available on this surface (freshness bound
             // only) — an orphaned snapshot must age out here too, not just on the
@@ -1061,8 +1005,23 @@ async function executeTool(name, args, ctx) {
                     '',
                 ].join('\n')
                 : '';
-            const memoryText = formatMemories(results, hippoRoot);
-            return snapshotText ? `${snapshotText}\n${memoryText}` : memoryText;
+            // The snapshot prints first, so it is paid first after the heading; context keeps no hit past the budget, even the top one.
+            let left = budget - memoriesReserve(budget);
+            if (left < 0)
+                return ''; // not even the heading fits, so nothing prints, as at budget 0
+            const snapshotPiece = snapshotText ? `${snapshotText}\n` : '';
+            const showSnapshot = snapshotPiece !== '' && estimateTokens(snapshotPiece) <= left;
+            if (showSnapshot)
+                left -= estimateTokens(snapshotPiece);
+            const usePhysicsCtx = config.physics?.enabled !== false;
+            const fit = { budget: left, minResults: 0, cost: memoryCost, hippoRoot };
+            const results = dropHeldCopies(usePhysicsCtx
+                ? await physicsSearch(query, entries, { ...fit, physicsConfig: config.physics })
+                : await hybridSearch(query, entries, fit), (r) => r.entry);
+            const retrievedIds = results.map((r) => r.entry.id);
+            strengthenRetrieved(hippoRoot, retrievedIds);
+            lastRecalledIds.set(resolveClientKey(ctx), retrievedIds);
+            return (showSnapshot ? snapshotPiece : '') + formatMemories(results);
         }
         case 'hippo_status': {
             const entries = loadAllEntries(hippoRoot, tenantId);
@@ -1108,8 +1067,9 @@ async function executeTool(name, args, ctx) {
             let added = 0;
             let skipped = 0;
             let rejected = 0;
+            const keys = storedTextKeys(loadAllEntries(hippoRoot, tenantId));
             for (const lesson of lessons) {
-                if (deduplicateLesson(hippoRoot, lesson, 0.7, tenantId)) {
+                if (keys.has(duplicateKey(lesson))) {
                     skipped++;
                     continue;
                 }
@@ -1133,6 +1093,7 @@ async function executeTool(name, args, ctx) {
                     }
                     throw err;
                 }
+                keys.add(duplicateKey(lesson));
                 added++;
             }
             const rejectedSuffix = rejected > 0 ? `, ${rejected} rejected values skipped` : '';

package/dist/memory.d.ts

@@ -213,8 +213,17 @@ export declare function resolveConfidence(entry: MemoryEntry, now?: Date): Confi
  * on an older base (src/half-life-migration.ts).
  */
 export declare const DEFAULT_HALF_LIFE_DAYS = 365;
-export declare const AUTO_DELETABLE_SQL = "pinned = 0 AND kind != 'raw'";
-export declare function canAutoDelete(entry: Pick<MemoryEntry, 'pinned' | 'kind'>): boolean;
+export declare const COMPACTION_MEMORY_TAG = "compaction-memory";
+export declare const COMPACTION_SOURCE_PREFIX = "compaction:";
+/** A row with `tag` and a source starting `sourcePrefix` is kept for good. Both, since merge copies source tags onto rows whose source is 'consolidation'. */
+export interface KeepPair {
+    readonly tag: string;
+    readonly sourcePrefix: string;
+}
+export declare const KEEP_PAIRS: readonly KeepPair[];
+export declare const AUTO_DELETABLE_SQL: string;
+export declare function isKeptForGood(entry: Pick<MemoryEntry, 'tags' | 'source' | 'superseded_by'>): boolean;
+export declare function canAutoDelete(entry: Pick<MemoryEntry, 'pinned' | 'kind' | 'tags' | 'source' | 'superseded_by'>): boolean;
 export interface CreateMemoryOptions {
     layer?: Layer;
     tags?: string[];
@@ -239,6 +248,14 @@ export interface CreateMemoryOptions {
 }
 /** Create a new memory entry with defaults. Untyped JavaScript callers that omit the options get the compiled default half-life. */
 export declare function createMemory(content: string, options: CreateMemoryOptions): MemoryEntry;
+/** The row that replaces `old`: a supersede never changes where a memory belongs, so source, scope, session and a stamped origin carry over. */
+export declare function createSuccessor(old: MemoryEntry, content: string, opts: {
+    tenantId: string;
+    baseHalfLifeDays: number;
+    layer?: Layer;
+    tags?: string[];
+    pinned?: boolean;
+}): MemoryEntry;
 /**
  * Compute how well new content fits existing knowledge patterns.
  * Returns 0..1 where:

package/dist/memory.js

@@ -4,6 +4,7 @@
  */
 import { randomUUID } from 'crypto';
 import { isDecayAblated, isOutcomeSlowAblated, isRecallBoostAblated, evalNow, } from './ablation.js';
+import { AGENT_MEMORY_TOOLS, toolSourcePrefix } from './agent-memories/tools.js';
 export var Layer;
 (function (Layer) {
     Layer["Buffer"] = "buffer";
@@ -314,10 +315,22 @@ export function resolveConfidence(entry, now = evalNow()) {
  * on an older base (src/half-life-migration.ts).
  */
 export const DEFAULT_HALF_LIFE_DAYS = 365;
-// Pinned means keep; raw rows leave only through archiveRawMemory. The SQL twin guards the DELETE itself.
-export const AUTO_DELETABLE_SQL = "pinned = 0 AND kind != 'raw'";
+export const COMPACTION_MEMORY_TAG = 'compaction-memory';
+export const COMPACTION_SOURCE_PREFIX = 'compaction:';
+export const KEEP_PAIRS = [
+    { tag: COMPACTION_MEMORY_TAG, sourcePrefix: COMPACTION_SOURCE_PREFIX },
+    ...AGENT_MEMORY_TOOLS.map((t) => ({ tag: t.tag, sourcePrefix: toolSourcePrefix(t.id) })),
+];
+const sqlText = (s) => `'${s.replace(/'/g, "''")}'`;
+// json_each matches the tag as a whole element; substr, not LIKE, keeps the prefix case-sensitive like startsWith.
+const keepPairSql = (p) => `(COALESCE(superseded_by, '') = '' AND EXISTS (SELECT 1 FROM json_each(CASE WHEN json_valid(tags_json) THEN tags_json ELSE '[]' END) WHERE value = ${sqlText(p.tag)}) AND substr(source, 1, ${p.sourcePrefix.length}) = ${sqlText(p.sourcePrefix)})`;
+// Pinned and kept rows stay (a superseded row is not kept: its successor carries the tag and source); raw rows leave only through archiveRawMemory. The SQL twin guards the DELETE itself.
+export const AUTO_DELETABLE_SQL = `pinned = 0 AND kind != 'raw'${KEEP_PAIRS.map((p) => ` AND NOT ${keepPairSql(p)}`).join('')}`;
+export function isKeptForGood(entry) {
+    return !entry.superseded_by && KEEP_PAIRS.some((p) => entry.tags.includes(p.tag) && entry.source.startsWith(p.sourcePrefix));
+}
 export function canAutoDelete(entry) {
-    return !entry.pinned && entry.kind !== 'raw';
+    return !entry.pinned && entry.kind !== 'raw' && !isKeptForGood(entry);
 }
 export function createMemory(content, options = {}) {
     const trimmed = content.trim();
@@ -373,6 +386,25 @@ export function createMemory(content, options = {}) {
     entry.strength = calculateStrength(entry);
     return entry;
 }
+/** The row that replaces `old`: a supersede never changes where a memory belongs, so source, scope, session and a stamped origin carry over. */
+export function createSuccessor(old, content, opts) {
+    const next = createMemory(content, {
+        layer: opts.layer ?? old.layer,
+        tags: opts.tags ?? [...old.tags],
+        pinned: opts.pinned ?? old.pinned,
+        source: old.source,
+        confidence: 'verified',
+        tenantId: opts.tenantId,
+        scope: old.scope,
+        source_session_id: old.source_session_id,
+        baseHalfLifeDays: opts.baseHalfLifeDays,
+    });
+    // A legacy null origin has nothing to carry, so the store stamps it from its own location.
+    if (typeof old.origin_project === 'string') {
+        next.origin_project = old.origin_project;
+    }
+    return next;
+}
 /**
  * Compute how well new content fits existing knowledge patterns.
  * Returns 0..1 where:

package/dist/merged-row.d.ts

@@ -0,0 +1,6 @@
+import { type MemoryEntry } from './memory.js';
+/** The row that replaces a merged row once its retired texts leave: undefined when it holds none, null when nothing else is left. */
+export declare function mergedSuccessor(row: MemoryEntry, retired: (text: string) => boolean, retiredIds: ReadonlySet<string>): MemoryEntry | null | undefined;
+/** Sleep's check on a merged row: drops texts whose source was superseded since the merge, or that a rejection now covers. */
+export declare function successorAfterRetirement(row: MemoryEntry, byId: ReadonlyMap<string, MemoryEntry>, rejected: (text: string) => boolean): MemoryEntry | null | undefined;
+//# sourceMappingURL=merged-row.d.ts.map

package/dist/merged-row.js

@@ -0,0 +1,35 @@
+// A sleep-merged row copies its sources' texts, so retiring a text (reject, or superseding its source) must reach the row too.
+// SHORTCUT: reject rewrites merged rows at once, live and dormant; supersede and `resolve --reject-loser` wait for the next sleep's check, which sees a dormant row only once restored.
+import { generateId } from './memory.js';
+import { duplicateKey, heldTexts, mergedText } from './same-text.js';
+/** The row that replaces a merged row once its retired texts leave: undefined when it holds none, null when nothing else is left. */
+export function mergedSuccessor(row, retired, retiredIds) {
+    const texts = heldTexts(row);
+    const kept = texts.filter((t) => !retired(t));
+    if (kept.length === texts.length)
+        return undefined;
+    if (kept.length === 0)
+        return null;
+    const count = `${kept.length} related ${kept.length === 1 ? 'memory' : 'memories'}`;
+    const header = row.content.slice(0, row.content.indexOf('\n\n')).replace(/\d+ related memor(?:y|ies)/, count);
+    // A new id, as a fresh merge would get; age and half-life carry over so the rewrite buys the row no extra life.
+    return {
+        ...row,
+        id: generateId('sem'),
+        content: mergedText(header, kept),
+        parents: row.parents.filter((id) => !retiredIds.has(id)),
+        conflicts_with: [],
+    };
+}
+/** Sleep's check on a merged row: drops texts whose source was superseded since the merge, or that a rejection now covers. */
+export function successorAfterRetirement(row, byId, rejected) {
+    if (row.source !== 'consolidation' || row.superseded_by)
+        return undefined;
+    const sources = row.parents.flatMap((id) => byId.get(id) ?? []);
+    const retiredIds = new Set(sources.filter((s) => Boolean(s.superseded_by) || rejected(s.content)).map((s) => s.id));
+    const live = new Set(sources.filter((s) => !retiredIds.has(s.id)).map((s) => duplicateKey(s.content)));
+    const gone = new Set(sources.filter((s) => retiredIds.has(s.id)).map((s) => duplicateKey(s.content)));
+    const retired = (text) => (gone.has(duplicateKey(text)) && !live.has(duplicateKey(text))) || rejected(text);
+    return mergedSuccessor(row, retired, retiredIds);
+}
+//# sourceMappingURL=merged-row.js.map

package/dist/multihop.d.ts

@@ -1,10 +1,11 @@
 import type { MemoryEntry } from './memory.js';
-import { type SearchResult } from './search.js';
+import { type ResultCost, type SearchResult } from './search.js';
 export declare function multihopSearch(query: string, entries: MemoryEntry[], options?: {
     budget?: number;
     now?: Date;
     hippoRoot?: string;
     minResults?: number;
+    cost?: ResultCost;
     includeSuperseded?: boolean;
     asOf?: string;
 }): SearchResult[];