hippo-memory 1.69.0 → 1.71.0

package/dist/{dag.d.ts → consolidate/dag.d.ts}

@@ -1,17 +1,11 @@
-import { type MemoryEntry } from './memory.js';
+import { type MemoryEntry } from '../core/memory.js';
+import { type DagSummaryOptions } from './dag-summary.js';
 export interface FactCluster {
     label: string;
     members: MemoryEntry[];
     entityTags: string[];
 }
 export declare function clusterFacts(facts: MemoryEntry[]): FactCluster[];
-export interface DagSummaryOptions {
-    apiKey: string;
-    model?: string;
-    fetcher?: typeof fetch;
-    onError?: (msg: string) => void;
-}
-export declare function generateDagSummary(label: string, factContents: string[], opts: DagSummaryOptions): Promise<string | null>;
 export interface DagBuildResult {
     candidateClusters: number;
     summariesCreated: number;
@@ -29,19 +23,8 @@ export interface DagRebuildResult {
     failed: number;
     capped: boolean;
 }
-/**
- * Sleep-cycle phase that drains the dirty L2 summary queue.
- * Thin orchestrator; the heavy lifting lives in store.ts (load + apply)
- * and dag.ts:generateDagSummary (LLM call).
- *
- * Per-summary try/catch: one throwing rebuild does NOT abort the rest of the queue.
- *
- * Race-loser handling: applyRebuildResult's UPDATE WHERE includes
- * AND summary_dirty=1, so concurrent sleep's second writer returns
- * changed=false. Silent skip (neither rebuilt++ nor refused++ nor failed++).
- *
- * A tombstone hit counts as `refused`, not `rebuilt`; dirty clears either way.
- */
+/** Sleep-cycle phase draining the dirty L2 summary queue; one throwing rebuild does not abort the rest.
+ * A concurrent sleep's second writer gets changed=false (UPDATE requires summary_dirty=1) and is skipped silently; a tombstone hit counts as `refused`. */
 export declare function rebuildDirtySummaries(hippoRoot: string, opts: DagSummaryOptions & {
     cap?: number;
 }): Promise<DagRebuildResult>;
@@ -54,13 +37,7 @@ export interface EntityProfilesBuildResult {
      *  `failed`: a tombstone hit is a deliberate refusal, not an error. */
     rejected: number;
 }
-/**
- * Build L3 entity profiles by clustering L2 summaries with
- * shared entity tags. Threshold 2+ L2s per entity. Mirrors buildDag L1->L2
- * pattern, one level up.
- *
- * Born-dirty cancellation: each L2 link write marks the new L3 dirty, so clear it
- * or the same sleep cycle's rebuild re-rebuilds the freshly built L3.
- */
+/** Build L3 entity profiles by clustering L2 summaries sharing entity tags (2+ L2s per entity).
+ * Each L2 link write marks the new L3 dirty, so clear it or the same cycle re-rebuilds it. */
 export declare function buildEntityProfiles(hippoRoot: string, l2Summaries: MemoryEntry[], opts: DagSummaryOptions): Promise<EntityProfilesBuildResult>;
 //# sourceMappingURL=dag.d.ts.map

package/dist/{dag.js → consolidate/dag.js}

@@ -1,14 +1,14 @@
-import { createMemory, Layer } from './memory.js';
-import { writeEntry } from './store/entry-writes.js';
-import { loadAllDirtySummaries, loadChildrenOfSummary, applyRebuildResult, clearSummaryDirtyAfterBuild, } from './store/summaries.js';
-import { RejectedValueError } from './rejection.js';
-import { redactSecretsStrict } from './secret-detect.js';
-import { fetchWithRetry, llmTimeoutMs } from './http-retry.js';
-import { derivationScope, derivationPartitionKey } from './recall-scope.js';
-import { loadConfig } from './config.js';
-import { neverAutoShareTags } from './shared.js';
-import { log } from './log.js';
-import { certainDefect } from './memory-quality.js';
+import { createMemory, Layer } from '../core/memory.js';
+import { writeEntry, writeEntriesTogether } from '../store/entry-writes.js';
+import { loadAllDirtySummaries, loadChildrenOfSummary, applyRebuildResult, clearSummaryDirtyAfterBuild, } from '../store/summaries.js';
+import { RejectedValueError } from '../store/rejection.js';
+import { generateDagSummary } from './dag-summary.js';
+import { derivationScope, derivationPartitionKey } from '../store/recall-scope.js';
+import { loadConfig } from '../core/config.js';
+import { neverAutoShareTags } from '../sharing/share.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
+const SUMMARY_FALLBACK_CHARS = 40;
+const DEFAULT_REBUILD_CAP = 20;
 export function clusterFacts(facts) {
     if (facts.length === 0)
         return [];
@@ -35,66 +35,12 @@ export function clusterFacts(facts) {
         const sharedTags = entityTags[cluster[0]].filter((t) => cluster.every((idx) => entityTags[idx].includes(t)));
         const label = sharedTags
             .map((t) => t.split(':')[1])
-            .join(': ') || members[0].content.slice(0, 40);
+            .join(': ') || members[0].content.slice(0, SUMMARY_FALLBACK_CHARS);
         clusters.push({ label, members, entityTags: sharedTags });
     }
     return clusters;
 }
-const DAG_SUMMARY_PROMPT = `You are summarizing a cluster of facts about a specific topic/entity for a memory system.
-
-Topic: {label}
-Facts:
-{facts}
-
-Write a single concise paragraph (2-4 sentences) that captures all the key information from these facts. This summary will be used to quickly determine if this cluster is relevant to a future query, so include specific names, dates, numbers, and key details. Output ONLY the summary paragraph, no preamble.`;
-export async function generateDagSummary(label, factContents, opts) {
-    const model = opts.model ?? 'claude-sonnet-4-6';
-    const fetchFn = opts.fetcher ?? fetch;
-    const factsBlock = factContents.map((f, i) => `${i + 1}. ${redactSecretsStrict(f)}`).join('\n');
-    const prompt = DAG_SUMMARY_PROMPT
-        .replace('{label}', redactSecretsStrict(label))
-        .replace('{facts}', factsBlock);
-    let res;
-    try {
-        res = await fetchWithRetry('https://api.anthropic.com/v1/messages', {
-            method: 'POST',
-            headers: {
-                'content-type': 'application/json',
-                'x-api-key': opts.apiKey,
-                'anthropic-version': '2023-06-01',
-            },
-            body: JSON.stringify({
-                model,
-                max_tokens: 400,
-                messages: [{ role: 'user', content: prompt }],
-            }),
-        }, { timeoutMs: llmTimeoutMs(), fetchFn });
-    }
-    catch (err) {
-        opts.onError?.(`request failed: ${err instanceof Error ? err.message : String(err)}`);
-        return null;
-    }
-    if (!res.ok) {
-        opts.onError?.(`HTTP ${res.status}`);
-        return null;
-    }
-    try {
-        const data = await res.json();
-        const text = data.content?.[0]?.text?.trim() ?? '';
-        const defect = certainDefect(text);
-        if (defect !== null) {
-            opts.onError?.(`summary quality refused: ${defect}`);
-            return null;
-        }
-        return text.length >= 20 ? text : null;
-    }
-    catch (err) {
-        opts.onError?.(`unparseable response: ${err instanceof Error ? err.message : String(err)}`);
-        return null;
-    }
-}
-// Partition BEFORE clustering so one LLM summary never mixes facts from different tenants.
-// Map keeps insertion order, so a single-tenant store iterates in its original order.
+// Partition before clustering so one LLM summary never mixes tenants; Map keeps insertion order, so a single-tenant store iterates as before.
 // buildEntityProfiles partitions its L2s with this same key.
 function partitionFactsByTenant(unparented) {
     const unparentedByTenant = new Map();
@@ -111,10 +57,7 @@ function partitionFactsByTenant(unparented) {
 /** The L2 summary entry for one cluster, landing in the facts' own tenant and scope. */
 function createClusterSummaryEntry(summary, cluster, home) {
     const memberCreatedAts = cluster.members.map((m) => m.created).sort();
-    // Every member of `cluster` shares home.tenantId by construction (the
-    // tenant partition above), so the summary lands in the same tenant
-    // as the facts it summarizes instead of always 'default'
-    // (memory.ts:535 defaults tenantId when the option is omitted).
+    // Every cluster member shares home.tenantId (tenant partition above), so the summary lands in the facts' tenant, not 'default'.
     const summaryEntry = createMemory(summary, {
         layer: Layer.Semantic,
         tags: [...cluster.entityTags, ...neverAutoShareTags(cluster.members), 'dag-summary'],
@@ -152,11 +95,7 @@ async function summarizeCluster(hippoRoot, cluster, home, opts, result) {
         throw err;
     }
     result.summariesCreated++;
-    for (const member of cluster.members) {
-        const updated = { ...member, dag_parent_id: summaryEntry.id };
-        writeEntry(hippoRoot, updated);
-        result.factsLinked++;
-    }
+    result.factsLinked += writeEntriesTogether(hippoRoot, cluster.members.map((member) => ({ ...member, dag_parent_id: summaryEntry.id })));
     // Member writes just marked this fresh summary dirty; clear it, or the same sleep cycle's
     // rebuild pass would re-rebuild every new summary at twice the LLM cost.
     clearSummaryDirtyAfterBuild(hippoRoot, summaryEntry.id, summaryEntry.tenantId, 'buildDag');
@@ -185,29 +124,10 @@ export async function buildDag(hippoRoot, facts, opts) {
 async function rebuildOneSummary(hippoRoot, summary, opts, result) {
     const children = loadChildrenOfSummary(hippoRoot, summary.id, summary.tenantId);
     if (children.length === 0) {
-        // Zero-child case: clear dirty + zero counts, no LLM call, no rebuild_count bump.
-        const { changed } = applyRebuildResult(hippoRoot, summary, {
-            content: summary.content,
-            descendant_count: 0,
-            earliest_at: null,
-            latest_at: null,
-            bumpRebuildCount: false,
-            zeroChildren: true,
-            actor: 'sleep',
-        });
-        if (changed)
-            result.zeroChildSkipped++;
-        // changed=false → race lost / row vanished; silently skip. `refused`
-        // is always false here — applyRebuildResult only checks the
-        // tombstone when bumpRebuildCount is true (store/summaries.ts).
+        clearZeroChildSummary(hippoRoot, summary, result);
         return;
     }
-    // Derive label from summary's existing entity tags (mirrors clusterFacts)
-    const entityTags = summary.tags.filter((t) => t.startsWith('speaker:') || t.startsWith('topic:'));
-    const label = entityTags.length > 0
-        ? entityTags.map((t) => t.split(':')[1]).join(': ')
-        : summary.content.slice(0, 40);
-    const newContent = await generateDagSummary(label, children.map((c) => c.content), opts);
+    const newContent = await generateDagSummary(summaryLabel(summary), children.map((c) => c.content), opts);
     if (!newContent) {
         // LLM null / fetch error → leave dirty for next cycle
         result.failed++;
@@ -232,21 +152,33 @@ async function rebuildOneSummary(hippoRoot, summary, opts, result) {
     // changed=false (refused also false) → race lost; not failure, not
     // success, silently skip
 }
-/**
- * Sleep-cycle phase that drains the dirty L2 summary queue.
- * Thin orchestrator; the heavy lifting lives in store.ts (load + apply)
- * and dag.ts:generateDagSummary (LLM call).
- *
- * Per-summary try/catch: one throwing rebuild does NOT abort the rest of the queue.
- *
- * Race-loser handling: applyRebuildResult's UPDATE WHERE includes
- * AND summary_dirty=1, so concurrent sleep's second writer returns
- * changed=false. Silent skip (neither rebuilt++ nor refused++ nor failed++).
- *
- * A tombstone hit counts as `refused`, not `rebuilt`; dirty clears either way.
- */
+/** Zero-child case: clear dirty + zero counts, no LLM call, no rebuild_count bump. */
+function clearZeroChildSummary(hippoRoot, summary, result) {
+    const { changed } = applyRebuildResult(hippoRoot, summary, {
+        content: summary.content,
+        descendant_count: 0,
+        earliest_at: null,
+        latest_at: null,
+        bumpRebuildCount: false,
+        zeroChildren: true,
+        actor: 'sleep',
+    });
+    if (changed)
+        result.zeroChildSkipped++;
+    // changed=false means race lost or row vanished: skip silently. `refused` is always false here, as applyRebuildResult
+    // checks the tombstone only when bumpRebuildCount is true.
+}
+// Derive label from summary's existing entity tags (mirrors clusterFacts)
+function summaryLabel(summary) {
+    const entityTags = summary.tags.filter((t) => t.startsWith('speaker:') || t.startsWith('topic:'));
+    return entityTags.length > 0
+        ? entityTags.map((t) => t.split(':')[1]).join(': ')
+        : summary.content.slice(0, SUMMARY_FALLBACK_CHARS);
+}
+/** Sleep-cycle phase draining the dirty L2 summary queue; one throwing rebuild does not abort the rest.
+ * A concurrent sleep's second writer gets changed=false (UPDATE requires summary_dirty=1) and is skipped silently; a tombstone hit counts as `refused`. */
 export async function rebuildDirtySummaries(hippoRoot, opts) {
-    const cap = opts.cap ?? 20;
+    const cap = opts.cap ?? DEFAULT_REBUILD_CAP;
     const dirty = loadAllDirtySummaries(hippoRoot);
     const capped = dirty.length > cap;
     const queue = dirty.slice(0, cap);
@@ -259,12 +191,8 @@ export async function rebuildDirtySummaries(hippoRoot, opts) {
         capped,
     };
     for (const [index, summary] of queue.entries()) {
-        // Yield the macrotask queue every 25 summaries. The cap can reach 1000,
-        // and each iteration is synchronous SQLite (the LLM await resolves as a
-        // microtask when the response is cached/mocked), so a large batch would
-        // otherwise starve timers and IPC for the whole rebuild: server
-        // keep-alive pings in production, Vitest's birpc heartbeat in tests
-        // (hardcoded 60s upstream, vitest-dev/vitest#8164).
+        // Yield the macrotask queue every 25 summaries: each iteration is synchronous SQLite, so a batch of up to 1000
+        // would starve timers and IPC (server keep-alives, Vitest's birpc heartbeat).
         if (index > 0 && index % 25 === 0) {
             await new Promise((resolve) => setImmediate(resolve));
         }
@@ -275,7 +203,7 @@ export async function rebuildDirtySummaries(hippoRoot, opts) {
             // One throw doesn't abort the queue; log enough to triage an exotic
             // failure (SQLite I/O, prepare), since audit() already catches its own.
             result.failed++;
-            log.error(`rebuildDirtySummaries: summary ${summary.id} (tenant ${summary.tenantId}) failed: ${err instanceof Error ? err.message : String(err)}`);
+            log.error(`rebuildDirtySummaries: summary ${summary.id} (tenant ${summary.tenantId}) failed: ${errorMessage(err)}`, errorFields(err));
         }
     }
     return result;
@@ -321,23 +249,13 @@ async function profileCluster(hippoRoot, cluster, home, opts, result) {
         throw err;
     }
     result.profilesCreated++;
-    for (const member of cluster.members) {
-        const updated = { ...member, dag_parent_id: profileEntry.id };
-        writeEntry(hippoRoot, updated);
-        result.l2sLinked++;
-    }
+    result.l2sLinked += writeEntriesTogether(hippoRoot, cluster.members.map((member) => ({ ...member, dag_parent_id: profileEntry.id })));
     // Re-linking just marked the fresh L3 dirty; clear it so this cycle's rebuild skips it.
     // The distinct source tags the audit row.
     clearSummaryDirtyAfterBuild(hippoRoot, profileEntry.id, home.tenantId, 'buildEntityProfiles', 'buildEntityProfiles-clean');
 }
-/**
- * Build L3 entity profiles by clustering L2 summaries with
- * shared entity tags. Threshold 2+ L2s per entity. Mirrors buildDag L1->L2
- * pattern, one level up.
- *
- * Born-dirty cancellation: each L2 link write marks the new L3 dirty, so clear it
- * or the same sleep cycle's rebuild re-rebuilds the freshly built L3.
- */
+/** Build L3 entity profiles by clustering L2 summaries sharing entity tags (2+ L2s per entity).
+ * Each L2 link write marks the new L3 dirty, so clear it or the same cycle re-rebuilds it. */
 export async function buildEntityProfiles(hippoRoot, l2Summaries, opts) {
     const result = {
         candidateClusters: 0,

package/dist/consolidate/decay.d.ts

@@ -1,5 +1,5 @@
-import { MemoryEntry } from '../memory.js';
-import { type MvRankInfo } from '../memory-value.js';
+import { MemoryEntry } from '../core/memory.js';
+import { type MvRankInfo } from './memory-value.js';
 import type { SleepRun } from './run.js';
 export declare const DECAY_THRESHOLD = 0.05;
 /** What the decay pass hands to the conflict check and the rescue audit at the end of the run. */

package/dist/consolidate/decay.js

@@ -1,18 +1,14 @@
-import { calculateStrength } from '../memory.js';
-import { detectSecret } from '../secret-detect.js';
-import { rescueSet, rankNonPinnedByTenant, validateWeights } from '../memory-value.js';
-import { MEMORY_VALUE_WEIGHTS, SOURCE_ARTIFACT_SHA256 } from '../memory-value-weights.js';
+import { calculateStrength } from '../core/memory.js';
+import { detectSecret } from '../util/secret-detect.js';
+import { rescueSet, rankNonPinnedByTenant, validateWeights } from './memory-value.js';
+import { MEMORY_VALUE_WEIGHTS, SOURCE_ARTIFACT_SHA256 } from './memory-value-weights.js';
+const STRENGTH_DECIMALS = 4;
 export const DECAY_THRESHOLD = 0.05;
-// A faded, unpinned, unrescued memory leaves active memory one of three
-// ways. A raw receipt is append-only: trg_memories_raw_append_only aborts
-// a DELETE, and with it this whole cycle's batch and every later sleep,
-// so it stays where it is (stored strength refreshed) but sits out the
-// rest of this cycle the way a deleted row would. Anything else goes
-// dormant when config.dormant is on, and is deleted otherwise.
-// Only called for rows `retirable` allows (never pinned, raw, kept for good or backing a first-class object).
+// Leaving active memory: a raw receipt stays (the append-only trigger aborts DELETE for the whole batch; stored strength refreshed) but sits out this cycle;
+// others go dormant when config.dormant is on, else are deleted. Only called for rows `retirable` allows.
 function retireFaded(run, entry, strength) {
     const { result } = run;
-    const why = `(strength ${strength.toFixed(4)} < ${DECAY_THRESHOLD})`;
+    const why = `(strength ${strength.toFixed(STRENGTH_DECIMALS)} < ${DECAY_THRESHOLD})`;
     // A faded secret is deleted, never kept dormant: keeping it would hold a
     // credential on disk that the user reasonably expects forgetting removed.
     if (run.config.dormant.enabled && !detectSecret(entry).flagged) {
@@ -35,11 +31,8 @@ function keepSurvivor(run, entry, strength) {
     run.result.decayed++;
     return updated;
 }
-// -------------------------------------------------------------------------
-// 1. Decay pass
-// -------------------------------------------------------------------------
-// Memory-value flag OFF runs the single-phase loop below. Flag ON classifies every entry with ZERO commits,
-// runs rescueSet per tenant, then commits; rescued entries stay full survivors for this cycle's later passes.
+// 1. Decay pass. Memory-value flag OFF runs the single-phase loop below; ON classifies every entry with zero commits, runs rescueSet per tenant, then commits.
+// Rescued entries stay full survivors for this cycle's later passes.
 export function decayPass(run) {
     if (run.config.memoryValue.enabled)
         return decayWithMemoryValue(run);
@@ -65,35 +58,41 @@ function reportNonFiniteScores(result, rankById) {
             `with non-finite computed features (never rescued): ${nonFiniteIds.join(', ')}`);
     }
 }
-function decayWithMemoryValue(run) {
-    const { all, now, result } = run;
-    // Carried forward to logRun, where the mv_rescue audit rows are written: writing them here, before
-    // batchWriteAndDelete, would assert rescues whose effects might never land if a later phase throws.
-    const rescuedEntries = [];
-    let rescuedIds = new Set();
-    let rankById = new Map();
-    // --- Phase 1: classify (zero commits) ---
+// --- Phase 1: classify (zero commits) ---
+function classifyByStrength(run) {
     const condemned = [];
     const strengthById = new Map();
-    for (const entry of all) {
-        const strength = calculateStrength(entry, now, run.decayOpts);
+    for (const entry of run.all) {
+        const strength = calculateStrength(entry, run.now, run.decayOpts);
         strengthById.set(entry.id, strength);
         if (run.retirable(entry) && strength < DECAY_THRESHOLD) {
             condemned.push(entry);
         }
     }
-    // --- Phase 2a: rescue decision (pure compute) ---
-    // Runs under --dry-run too (only the pendingDeletes flush and the audit write in
-    // logRun stay !dryRun-gated), so the preview matches what a
-    // real run would decide.
-    const condemnedIds = new Set(condemned.map((e) => e.id));
+    return { strengthById, condemnedIds: new Set(condemned.map((e) => e.id)) };
+}
+function reportRescue(result, entry, strength, rank) {
+    const rankNote = rank
+        ? ` - rescued (rank ${rank.rank}/${rank.totalNonPinned} in tenant ${rank.tenantId}, top ${rank.keepN})`
+        : ' - rescued';
+    result.details.push(`  🛟 ${entry.id} (strength ${strength.toFixed(STRENGTH_DECIMALS)} < ${DECAY_THRESHOLD})${rankNote}`);
+}
+function decayWithMemoryValue(run) {
+    const { all, now, result } = run;
+    // Carried forward to logRun, where the mv_rescue audit rows are written: writing them here, before
+    // batchWriteAndDelete, would assert rescues whose effects might never land if a later phase throws.
+    const rescuedEntries = [];
+    let rescuedIds = new Set();
+    let rankById = new Map();
+    const { strengthById, condemnedIds } = classifyByStrength(run);
+    // Phase 2a: rescue decision (pure compute); runs under --dry-run too (only the pendingDeletes flush and the logRun audit write are !dryRun-gated).
     // Fail-loud must not depend on condemnation traffic: validate the frozen weights even when nothing is condemned.
     validateWeights();
     if (condemnedIds.size > 0) {
         // Rank per tenant ONCE: rankById feeds both rescueSet (via precomputedRanks) and the detail/audit
         // context below, so the whole-store ranking runs once per sleep and only when something is condemned.
         rankById = rankNonPinnedByTenant(all, now);
-        rescuedIds = rescueSet(all, condemnedIds, now, MEMORY_VALUE_WEIGHTS, SOURCE_ARTIFACT_SHA256, rankById);
+        rescuedIds = rescueSet(all, condemnedIds, now, { weights: MEMORY_VALUE_WEIGHTS, digest: SOURCE_ARTIFACT_SHA256, precomputedRanks: rankById });
         reportNonFiniteScores(result, rankById);
     }
     // --- Phase 2b: commit, one pass over `all` in ITS ORIGINAL ORDER ---
@@ -102,15 +101,10 @@ function decayWithMemoryValue(run) {
         const strength = strengthById.get(entry.id);
         if (run.retirable(entry) && strength < DECAY_THRESHOLD) {
             if (rescuedIds.has(entry.id)) {
-                // Rescued: standard survivor stored-strength refresh.
-                // Confidence is left alone here: it is an epistemic tier, not a
-                // cached computation, so resolveConfidence derives it on read.
+                // Rescued: standard survivor stored-strength refresh. Confidence is left alone: it is an epistemic tier, not a cached
+                // computation, so resolveConfidence derives it on read.
                 rescuedEntries.push(keepSurvivor(run, entry, strength));
-                const rank = rankById.get(entry.id);
-                const rankNote = rank
-                    ? ` - rescued (rank ${rank.rank}/${rank.totalNonPinned} in tenant ${rank.tenantId}, top ${rank.keepN})`
-                    : ' - rescued';
-                result.details.push(`  🛟 ${entry.id} (strength ${strength.toFixed(4)} < ${DECAY_THRESHOLD})${rankNote}`);
+                reportRescue(result, entry, strength, rankById.get(entry.id));
             }
             else {
                 retireFaded(run, entry, strength);

package/dist/consolidate/dedupe.d.ts

@@ -0,0 +1,29 @@
+/** Store-level dedup: same text apart from spacing, keeping the stronger copy; split out so `api.sleep` can dedupe without cli -> api imports.
+ * Survivor order is total and tenant-scoped: strength bucket, retrieval_count, then compareEntryIdentity; raw and superseded rows are not candidates. */
+export interface DedupPair {
+    kept: string;
+    keptContent: string;
+    keptLayer: string;
+    keptStrength: number;
+    removed: string;
+    removedContent: string;
+    removedLayer: string;
+    removedStrength: number;
+    similarity: number;
+}
+/** Result of `deduplicateStore`: how many entries were removed, and the kept/removed pairs. */
+export interface DedupResult {
+    removed: number;
+    pairs: DedupPair[];
+}
+/** Quantize strength to an integer bucket so ties are a true equivalence relation (equal iff same multiple of `STRENGTH_TIE_EPSILON`).
+ * Non-finite input maps to 0: a NaN bucket would make the comparator return NaN and break the total order. */
+export declare function strengthBucket(strength: number | null | undefined): number;
+/** Remove the weaker copy of same-text (apart from spacing) memories within one tenant; cross-tenant pairs are never duplicates (isolation boundary).
+ * Higher strength wins, then more retrievals; `threshold` is accepted for old callers and ignored. */
+export declare function deduplicateStore(hippoRoot: string, options?: {
+    threshold?: number;
+    dryRun?: boolean;
+    actor?: string;
+}): DedupResult;
+//# sourceMappingURL=dedupe.d.ts.map

package/dist/consolidate/dedupe.js

@@ -0,0 +1,103 @@
+/** Store-level dedup: same text apart from spacing, keeping the stronger copy; split out so `api.sleep` can dedupe without cli -> api imports.
+ * Survivor order is total and tenant-scoped: strength bucket, retrieval_count, then compareEntryIdentity; raw and superseded rows are not candidates. */
+import { textOverlap } from '../util/tokenize.js';
+import { loadCurrentDistilledEntries } from '../store/entry-reads.js';
+import { deleteEntriesOneByOne, memoriesBackingObjects } from '../store/delete-and-batch.js';
+import { compareEntryIdentity } from '../core/compare.js';
+import { canAutoDelete } from '../core/memory.js';
+import { derivationPartitionKey } from '../store/recall-scope.js';
+import { duplicateKey } from '../util/same-text.js';
+/** Quantization step for strength-tie comparisons: the 0.01 epsilon applied by rounding instead of an abs-diff threshold, so the tiebreak is transitive. */
+const STRENGTH_TIE_EPSILON = 0.01;
+/** Quantize strength to an integer bucket so ties are a true equivalence relation (equal iff same multiple of `STRENGTH_TIE_EPSILON`).
+ * Non-finite input maps to 0: a NaN bucket would make the comparator return NaN and break the total order. */
+export function strengthBucket(strength) {
+    const s = strength ?? 0;
+    return Number.isFinite(s) ? Math.round(s / STRENGTH_TIE_EPSILON) : 0;
+}
+// finiteCount hardens the retrieval leg like strengthBucket: a NaN would break the total order.
+// Unreachable via the schema (non-nullable INTEGER column); kept for symmetry.
+const finiteCount = (n) => Number.isFinite(n ?? 0) ? (n ?? 0) : 0;
+/** The v1.26.3 survivor total order: strength bucket desc, then retrieval_count desc, then compareEntryIdentity. */
+function survivorOrder(a, b) {
+    const bucketDiff = strengthBucket(b.strength) - strengthBucket(a.strength);
+    if (bucketDiff !== 0)
+        return bucketDiff;
+    const retrievalDiff = finiteCount(b.retrieval_count) - finiteCount(a.retrieval_count);
+    if (retrievalDiff !== 0)
+        return retrievalDiff;
+    return compareEntryIdentity(a, b);
+}
+// Tenant partition: group by tenantId before sorting so a duplicate pair never forms across tenants; Map keeps insertion order,
+// so a single-tenant store gets one group and the same result as a global pass.
+function entriesByPartition(entries) {
+    const entriesByTenant = new Map();
+    for (const entry of entries) {
+        // EI2: also split by restricted scope, else a private copy can delete the readable one.
+        const key = derivationPartitionKey(entry.tenantId, entry.scope, entry.origin_project);
+        const bucket = entriesByTenant.get(key);
+        if (bucket)
+            bucket.push(entry);
+        else
+            entriesByTenant.set(key, [entry]);
+    }
+    return entriesByTenant;
+}
+function dedupPair(kept, dropped) {
+    return {
+        kept: kept.id,
+        keptContent: kept.content,
+        keptLayer: kept.layer,
+        keptStrength: kept.strength ?? 0,
+        removed: dropped.id,
+        removedContent: dropped.content,
+        removedLayer: dropped.layer,
+        removedStrength: dropped.strength ?? 0,
+        similarity: textOverlap(kept.content, dropped.content),
+    };
+}
+/** Pairs within one partition, already in survivor order, grouped by survivor; marks each loser in `removed`. */
+function partitionPairs(tenantEntries, removed, backing) {
+    const groups = new Map();
+    for (const entry of tenantEntries) {
+        const key = duplicateKey(entry.content);
+        const group = groups.get(key);
+        if (!group) {
+            groups.set(key, { survivor: entry, pairs: [] });
+            continue;
+        }
+        if (!canAutoDelete(entry) || backing.has(entry.id))
+            continue;
+        removed.add(entry.id);
+        group.pairs.push(dedupPair(group.survivor, entry));
+    }
+    return [...groups.values()].flatMap((group) => group.pairs);
+}
+/** Remove the weaker copy of same-text (apart from spacing) memories within one tenant; cross-tenant pairs are never duplicates (isolation boundary).
+ * Higher strength wins, then more retrievals; `threshold` is accepted for old callers and ignored. */
+export function deduplicateStore(hippoRoot, options = {}) {
+    const dryRun = options.dryRun ?? false;
+    // Only current distilled rows compete: raw rows are append-only (the delete
+    // trigger would abort sleep mid-loop) and superseded rows are history.
+    const entries = loadCurrentDistilledEntries(hippoRoot);
+    const entriesByTenant = entriesByPartition(entries);
+    // Shared across tenant groups: ids are globally unique UUIDs, so `removed` cannot collide across tenants and deleteEntry deletes by primary key alone.
+    const removed = new Set();
+    const pairs = [];
+    const backing = memoriesBackingObjects(hippoRoot);
+    for (const tenantEntries of entriesByTenant.values()) {
+        // The survivor total order (see the file-level docstring), scoped per
+        // tenant group: the total order holds within a tenant only, matching the partition above.
+        tenantEntries.sort(survivorOrder);
+        pairs.push(...partitionPairs(tenantEntries, removed, backing));
+    }
+    const done = dryRun ? pairs : deletePairs(hippoRoot, pairs, options.actor);
+    return { removed: done.length, pairs: done };
+}
+/** The pairs whose loser was deleted; one store handle, one transaction per delete. */
+function deletePairs(hippoRoot, pairs, actor) {
+    const targets = pairs.map((p) => ({ id: p.removed, reason: `dedup: duplicate of ${p.kept}` }));
+    const gone = deleteEntriesOneByOne(hippoRoot, targets, { actor, automatic: true });
+    return pairs.filter((_, i) => gone[i]);
+}
+//# sourceMappingURL=dedupe.js.map

package/dist/consolidate/flush-units.d.ts

@@ -1,9 +1,8 @@
-import type { MemoryEntry } from '../memory.js';
-import type { DormantMove } from '../dormant.js';
-import type { FlushComponent } from '../store/delete-and-batch.js';
+import type { MemoryEntry } from '../core/memory.js';
+import type { DormantMove } from '../store/dormant.js';
+import type { FlushComponent, LoadedRows } from '../store/delete-and-batch.js';
 /** Components that share no id, ordered by each one's first op across writes, then deletes, then dormant moves. */
 export declare function groupFlush(writes: readonly MemoryEntry[], deletes: readonly string[], dormant: readonly DormantMove[], units: readonly (readonly string[])[]): FlushComponent[];
-/** [child, parent] for each queued op on a child whose DAG parent the run removes: a child's change marks the parent
- *  dirty, and one transaction always applied that mark after the parent was gone, so it audited nothing. */
-export declare function familyUnits(writes: readonly MemoryEntry[], deletes: readonly string[], dormant: readonly DormantMove[], snapshot: ReadonlyMap<string, MemoryEntry>): string[][];
+/** [child, parent] per queued op on a child whose DAG parent the run removes: the parent-dirty mark otherwise lands after the parent is gone. */
+export declare function familyUnits(writes: readonly MemoryEntry[], deletes: readonly string[], dormant: readonly DormantMove[], snapshot: LoadedRows): string[][];
 //# sourceMappingURL=flush-units.d.ts.map

package/dist/consolidate/flush-units.js

@@ -42,9 +42,9 @@ function unionFind(units) {
     }
     return find;
 }
-/** [child, parent] for each queued op on a child whose DAG parent the run removes: a child's change marks the parent
- *  dirty, and one transaction always applied that mark after the parent was gone, so it audited nothing. */
-// SHORTCUT: a removed parent and all its changed children commit as one component, so one hold can pass holdMs by a family's size; split by child if a family grows large.
+/** [child, parent] per queued op on a child whose DAG parent the run removes: the parent-dirty mark otherwise lands after the parent is gone. */
+// SHORTCUT: a removed parent and all its changed children commit as one component, so
+// one hold can pass holdMs by a family's size; split by child if a family grows large.
 export function familyUnits(writes, deletes, dormant, snapshot) {
     const removing = new Set([...deletes, ...dormant.map((m) => m.entry.id)]);
     const units = [];

package/dist/consolidate/half-life-migration.d.ts

@@ -0,0 +1,34 @@
+/** Moves a store's memories to a new default half-life: only memories still on the old base are rescaled (`deriveHalfLife(from, entry)` plus recall bonus).
+ * Memories hippo shortened since, or with their own fixed half-life, keep theirs; rescales are audit-logged and `meta` records the base, so it runs once. */
+import { type MemoryEntry } from '../core/memory.js';
+import { HALF_LIFE_BASE_META_KEY, LEGACY_TYPED_HALF_LIFE } from '../store/open.js';
+export { HALF_LIFE_BASE_META_KEY, LEGACY_TYPED_HALF_LIFE };
+/** What {@link migrateDefaultHalfLife} did, or would do under `dryRun`. */
+export interface HalfLifeMigrationResult {
+    from: number;
+    to: number;
+    /** Memories moved to the new base. */
+    rescaled: number;
+    /** Memories of decisions, incidents and other objects moved off the flat 90 days. */
+    typed: number;
+    /** Memories left alone because they are not on the old base. */
+    kept: number;
+    dryRun: boolean;
+    /** New half-life per moved id, so a dry run can preview decay at the new base. */
+    halfLives: ReadonlyMap<string, number>;
+}
+type HalfLifeFields = Pick<MemoryEntry, 'half_life_days' | 'tags' | 'schema_fit' | 'retrieval_count' | 'superseded_by'>;
+/** Recall bonus over `written`, the half-life `entry` got at write, or null when off it; each recall added 2 days. */
+export declare function halfLifeRecallBonus(entry: HalfLifeFields, written: number): number | null;
+/** The entries to rescale from `from` to `to`, as copies that keep their recall bonus. Pure. */
+export declare function planHalfLifeMigration(entries: readonly MemoryEntry[], from: number, to: number): MemoryEntry[];
+/** Memories of decisions, incidents and other objects still on the flat 90 days, as copies on `to` that keep their recall bonus. Pure. */
+export declare function planTypedHalfLifeMigration(entries: readonly MemoryEntry[], to: number): MemoryEntry[];
+/** The base this store's memories are on. */
+export declare function storeHalfLifeBase(hippoRoot: string): number;
+/** Move the store's memories, and those of objects on the old flat 90 days, from their recorded base to `to`, once; `dryRun` writes nothing. */
+export declare function migrateDefaultHalfLife(hippoRoot: string, to: number, opts?: {
+    dryRun?: boolean;
+    actor?: string;
+}): HalfLifeMigrationResult;
+//# sourceMappingURL=half-life-migration.d.ts.map