hippo-memory 1.70.0 → 1.71.0

package/dist/consolidate/memory-value.js

@@ -1,23 +1,6 @@
-/**
- * Learned memory-value scorer, wired into the sleep decay pass as a
- * rescue-only veto.
- *
- * computeMvFeatures mirrors benchmarks/memory-value/extract.mjs's
- * computeFeatures for the 8 live dims the fitter optimized over
- * (FIT_DIMS) — the only dims MEMORY_VALUE_WEIGHTS carries a weight for.
- * Any future edit to either side must keep them byte-equivalent; the parity
- * test in tests/memory-value-wiring.test.ts enforces this.
- *
- * scoreEntries mirrors benchmarks/memory-value/evaluate.mjs's per-store
- * min-max normalization + weighted scorer (no additional orientation
- * multiply — the frozen weights already encode sign/orientation).
- *
- * rescueSet implements rescue-only semantics: a condemned entry is
- * rescued iff its learned score ranks in the top 30% (RESCUE_BUDGET, the
- * measured keep-budget operating point) of its own tenant's non-pinned
- * candidate set. Deletes(flag-on) subset Deletes(flag-off) by construction — this
- * function can only ever shrink the condemned set, never grow it.
- */
+/** Learned memory-value scorer, a rescue-only veto in the sleep decay pass (it can only shrink the condemned set); mirrors benchmarks/memory-value/*.mjs.
+ * rescueSet rescues a condemned entry iff it ranks in the top 30% (RESCUE_BUDGET) of its tenant's non-pinned set; memory-value-wiring.test.ts guards parity. */
+import { DEFAULT_TENANT_ID } from '../util/env.js';
 import { calculateStrength } from '../core/memory.js';
 import { compareEntryIdentity } from '../core/compare.js';
 import { MEMORY_VALUE_WEIGHTS, SOURCE_ARTIFACT_SHA256 } from './memory-value-weights.js';
@@ -36,32 +19,11 @@ export const MV_FEATURE_NAMES = [
 /** The keep-budget operating point (the only point with measured
  *  evidence): a code constant tied to that evidence, not user-tunable. */
 const RESCUE_BUDGET = 0.3;
-/**
- * Small-tenant degeneracy: below this per-tenant non-pinned candidate-set
- * size, a rank statistic is noise (the measured evidence says nothing about
- * tiny scale), and the floor prevents immortal-entry
- * convergence: keepN=ceil(0.3*N) guarantees >=1 rescue at N=1, so without a
- * floor a condemned-only 1-entry tenant would be rescued every single sleep
- * forever. A condemned-only tenant below the floor instead drains normally
- * as entries are deleted: the surviving rescued subset only ever shrinks
- * toward 0, never regrows past 10 to regain eligibility on its own. Code
- * constant tied to that reasoning, not user-tunable (same posture as
- * RESCUE_BUDGET).
- */
+/** Per-tenant floor on the non-pinned candidate set: below it ranks are noise, and keepN=ceil(0.3*N) would rescue a 1-entry tenant's entry every sleep forever.
+ * A code constant tied to that reasoning, not user-tunable (like RESCUE_BUDGET). */
 const MIN_RESCUE_GROUP = 10;
-/**
- * Blind v1 feature dict for one MemoryEntry, restricted to the 8 dims the
- * frozen weights carry (mirrors extract.mjs's computeFeatures).
- *
- * CRITICAL: `strength` is CLOCK-BASIS `calculateStrength(entry, now)` with
- * NO DecayOptions — that is how the frozen weights' training features were
- * computed (extract.mjs never passes decayOpts). Passing the production
- * decay basis (config.decayBasis via consolidate.ts's decayOpts) into this
- * feature would silently break parity with the frozen weight vector. This
- * is an intentional divergence from the condemnation TRIGGER in
- * consolidate.ts, which keeps using decayOpts as today — only the rescue
- * FEATURE is clock-basis.
- */
+/** Blind v1 feature dict for one entry, restricted to the 8 dims the frozen weights carry. `strength` is CLOCK-BASIS `calculateStrength(entry, now)` with no
+ * DecayOptions, as in the weights' training; passing the production decay basis would silently break parity with the frozen weights. */
 export function computeMvFeatures(entry, now) {
     const ageDays = (now.getTime() - Date.parse(entry.created)) / DAY_MS;
     const pos = entry.outcome_positive ?? 0;
@@ -77,16 +39,8 @@ export function computeMvFeatures(entry, now) {
         content_length: entry.content.length,
     };
 }
-/**
- * Throws if the weight constant is malformed: fewer/extra dims, a
- * non-finite weight value, or a missing source digest. Flag-on + a broken
- * constant must THROW, never silently behave as flag-off.
- *
- * Parameterized (defaults to the real frozen singleton) so the throw
- * conditions are directly unit-testable without mutating the frozen
- * MEMORY_VALUE_WEIGHTS export — mirrors fit.mjs's verifyFrozenWeights
- * (see tests/memory-value-fit.test.ts's `describe('verifyFrozenWeights')`).
- */
+/** Throws on a malformed weight constant (wrong dims, non-finite weight, missing digest): flag-on with a broken constant must throw, never act as flag-off.
+ * Parameterized (default: the frozen singleton) so the throw paths are unit-testable. */
 function isFiniteWeightValue(value) {
     return typeof value === 'number' && Number.isFinite(value);
 }
@@ -105,25 +59,8 @@ export function validateWeights(weights = MEMORY_VALUE_WEIGHTS, digest = SOURCE_
         throw new Error('memory-value: weights constant is malformed — SOURCE_ARTIFACT_SHA256 digest missing (src/consolidate/memory-value-weights.ts)');
     }
 }
-/**
- * Min-max normalize each of the 8 features over the given entry set
- * (constant feature -> 0, matching evaluate.mjs), then score = dot(weights,
- * normalized). The normalization context is exactly the entries passed in —
- * callers control the bounded scope (per-tenant, non-pinned).
- *
- * `weights` defaults to the real frozen singleton; parameterized (like
- * validateWeights) so callers/tests can score against an explicit vector
- * without touching the module singleton.
- *
- * Non-finite features: Date.parse on a malformed `created`
- * string yields NaN, and NaN would silently corrupt every OTHER entry's
- * min-max in the same group. An entry with ANY non-finite computed feature
- * is excluded from the normalization context entirely (its raw values never
- * touch min/max) and always scores -Infinity — the lowest possible score, so
- * it sorts to the bottom of its tenant deterministically and (via rescueSet's
- * explicit finite-score guard below) can never be rescued. Conservative
- * direction: deletes(flag-on) subset deletes(flag-off) still holds.
- */
+/** Min-max normalize the 8 features over the given entries (constant -> 0), then score = dot(weights, normalized); callers set the scope.
+ * An entry with any non-finite feature (NaN from a malformed `created`) is excluded from normalization and scores -Infinity, so it can never be rescued. */
 export function scoreEntries(entries, now, weights = MEMORY_VALUE_WEIGHTS) {
     const raw = new Map();
     for (const e of entries)
@@ -166,17 +103,8 @@ export function scoreEntries(entries, now, weights = MEMORY_VALUE_WEIGHTS) {
     }
     return scores;
 }
-/**
- * Groups non-pinned entries by tenantId, scores + ranks each tenant's
- * group independently, and returns per-entry rank context for every
- * non-pinned entry (not just condemned ones) — the shared basis for both
- * rescueSet's rescue decision and consolidate.ts's audit-row rank context,
- * so the two never compute the ranking differently.
- *
- * `weights`/`digest` default to the real frozen singleton — parameterized
- * (like validateWeights/scoreEntries) purely for direct unit-testability of
- * the fail-loud path, never overridden by production callers.
- */
+/** Group non-pinned entries by tenantId, score and rank each group independently, and return rank context for every non-pinned entry;
+ * rescueSet and the consolidate audit rows share it so they never compute the ranking differently. */
 export function rankNonPinnedByTenant(entries, now, weights = MEMORY_VALUE_WEIGHTS, digest = SOURCE_ARTIFACT_SHA256) {
     validateWeights(weights, digest);
     const byTenant = new Map();
@@ -185,7 +113,7 @@ export function rankNonPinnedByTenant(entries, now, weights = MEMORY_VALUE_WEIGH
             continue; // pinned entries never compete for rescue (never condemned)
         // Default an undefined tenantId as dag.ts:341 does: a raw/legacy row can carry one at runtime,
         // and keying it "undefined" would split it into its own singleton tenant.
-        const tenantId = e.tenantId ?? 'default';
+        const tenantId = e.tenantId ?? DEFAULT_TENANT_ID;
         const list = byTenant.get(tenantId);
         if (list)
             list.push(e);
@@ -217,24 +145,8 @@ export function rankNonPinnedByTenant(entries, now, weights = MEMORY_VALUE_WEIGH
     }
     return result;
 }
-/**
- * Rescue decision: a condemned entry is rescued iff it ranks in the top
- * 30% of its tenant's non-pinned candidate set by learned score. Returns the
- * subset of condemnedIds that are rescued — the caller filters commits
- * (rescued -> survivors) and threads the same set into detectConflicts.
- *
- * `weights`/`digest` default to the real frozen singleton; production
- * callers (consolidate.ts) never pass overrides — the params exist purely so
- * "flag on + a broken constant throws" is directly testable end-to-end
- * through this function without mutating the frozen module singleton.
- *
- * `precomputedRanks`: when the caller has already
- * computed the per-tenant ranking (e.g. consolidate.ts needs it separately
- * for detail/audit rank context), pass it here to skip the internal
- * rankNonPinnedByTenant call — the whole-store ranking pass then runs
- * exactly once per sleep instead of twice. Omitted (the default), rescueSet
- * computes it internally as before — existing callers/tests are unaffected.
- */
+/** Rescue decision: the subset of condemnedIds ranking in the top 30% of their tenant's non-pinned set by learned score.
+ * Pass `precomputedRanks` to skip the internal ranking so the whole-store pass runs once per sleep; `weights`/`digest` overrides exist for tests only. */
 export function rescueSet(entries, condemnedIds, now, options = {}) {
     const { weights = MEMORY_VALUE_WEIGHTS, digest = SOURCE_ARTIFACT_SHA256, precomputedRanks } = options;
     validateWeights(weights, digest); // fail loud before any rescue computation

package/dist/consolidate/merge.js

@@ -14,11 +14,8 @@ const MERGE_OVERLAP_THRESHOLD = 0.35; // Jaccard similarity for "related"
 const MERGE_MIN_CLUSTER = 2; // minimum cluster size to merge
 const MERGE_MAX_SOURCES = 5; // with MERGE_MAX_CHARS, keeps a merged row near 500 tokens, a third of the 1,500-token context budget
 const MERGE_MAX_CHARS = 2000; // total source text; sources past either cap stay unmerged and keep their half-life
-// Half-life scale for merged source episodics. Demotion must go through
-// half_life_days: calculateStrength() recomputes live strength from
-// last_retrieved/half_life and never reads the stored strength field, so a
-// stored-strength write is inert for ranking and gets overwritten by the
-// next sleep's decay pass anyway.
+// Half-life scale for merged source episodics. Demote via half_life_days: calculateStrength() recomputes live strength and never reads the stored field,
+// so a stored-strength write is inert for ranking and overwritten by the next decay pass.
 const MERGE_SOURCE_HALF_LIFE_FACTOR = 0.3;
 export function retireHeldTexts(run) {
     const { survivors } = run;
@@ -63,9 +60,7 @@ function partitionMergeCandidates(survivors) {
     }
     return mergeCandidatesByTenant;
 }
-// -------------------------------------------------------------------------
 // 3. Merge pass  - episodic entries only
-// -------------------------------------------------------------------------
 /** Returns how many clusters were skipped because their merged text matches a rejected value. */
 export function mergePass(run) {
     const used = new Set();
@@ -123,16 +118,8 @@ function mergeCluster(run, partition, cluster, related, used) {
         run.pendingWrites.push(semantic);
         run.units.push([semantic.id, ...cluster.map((e) => e.id)]);
         result.semanticCreated++;
-        // Demote source episodics (they've been compressed into neocortex):
-        // scale half_life_days so they decay sooner while staying recoverable.
-        // Immediate ranking is deliberately unchanged: dropping children below a
-        // worse-retrieving summary regresses budget-bounded QA. The stored
-        // strength is refreshed to the live value so inspect, replay sampling,
-        // and strength-sorted assembly see the truth instead of a fake 0.3.
-        // Mutate in place (not a copy): `cluster` holds the same object
-        // references as `survivors`, and the later detectConflicts(survivors)
-        // pass in this same run must see the post-demotion half-life, or it
-        // can persist conflicts for entries the just-written state excludes.
+        // Scale half_life_days so merged sources decay sooner but stay recoverable; ranking is unchanged on purpose (demoting children regresses QA).
+        // Mutate in place: `cluster` shares references with `survivors`, and the later detectConflicts(survivors) must see the post-demotion half-life.
         demoteMergedSources(run, cluster);
     }
     return true;
@@ -163,14 +150,8 @@ function demoteMergedSources(run, cluster) {
         run.pendingWrites.push(e);
     }
 }
-// mergeContents is DETERMINISTIC CONCATENATION (not an LLM paraphrase)
-// — if a human rejected exactly this byte-identical rollup before, an
-// unguarded sleep would regenerate it every cycle and
-// batchWriteAndDelete's guard bypass (store.ts) would silently
-// re-assert it forever. This producer-side check is what makes that
-// bypass safe. A hit skips the WHOLE cluster: sources stay unmerged —
-// not demoted, not deleted — so a later sleep gets another chance if
-// the tombstone is lifted.
+// mergeContents is deterministic, so a rollup a human already rejected would regenerate each cycle and batchWriteAndDelete's guard bypass would re-assert it;
+// this producer-side check makes that bypass safe. A hit skips the whole cluster (no demote, no delete) so a later sleep can retry.
 function mergeRejected(run, semantic, cluster, related, used) {
     const { tombstones } = run;
     const newDigest = rejectionDigest(semantic.content);
@@ -180,9 +161,7 @@ function mergeRejected(run, semantic, cluster, related, used) {
     const mergeDigest = newHit ? newDigest : oldDigest;
     if (!tombstone)
         return false;
-    // Still mark used — these members are not re-tried against a
-    // DIFFERENT cluster within this same pass; next sleep re-clusters
-    // them fresh.
+    // Still mark used: these members are not re-tried against a different cluster in this pass; the next sleep re-clusters them fresh.
     const rejected = newHit ? cluster : related; // the old format digested the uncapped list, so rows past the cap were rejected too
     for (const e of rejected)
         used.add(e.id);
@@ -203,9 +182,7 @@ function mergeRejected(run, semantic, cluster, related, used) {
     }
     return true;
 }
-// ---------------------------------------------------------------------------
 // Helpers
-// ---------------------------------------------------------------------------
 function mergeContents(entries) {
     // Each distinct text goes in once and in full (the merge demotes every source), one bullet with its lines indented, so heldTextKeys can read it back.
     // Newest first says which version is current; compareEntryIdentity settles ties, so the row and its rejection digest depend only on the sources.
@@ -215,7 +192,9 @@ function mergeContents(entries) {
         if (!texts.has(duplicateKey(e.content)))
             texts.set(duplicateKey(e.content), e.content);
     }
-    const header = entries.length === 2 ? '[Consolidated from 2 related memories, newest first]' : `[Consolidated pattern from ${entries.length} related memories, newest first]`;
+    const header = entries.length === 2
+        ? '[Consolidated from 2 related memories, newest first]'
+        : `[Consolidated pattern from ${entries.length} related memories, newest first]`;
     return mergedText(header, [...texts.values()]);
 }
 function legacyMergeContents(entries) {

package/dist/consolidate/merged-row.js

@@ -1,5 +1,6 @@
 // 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.
+// 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 '../core/memory.js';
 import { duplicateKey, heldTexts, mergedText } from '../util/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. */

package/dist/consolidate/physics-pass.js

@@ -1,11 +1,9 @@
 import { refreshParticleProperties } from '../db/physics-state.js';
-import { loadStoredParticles, saveStoredParticles } from '../store/vector-writes.js';
+import { loadStoredParticles, saveStoredParticles } from '../store/vector-index.js';
 import { simulate } from '../core/physics.js';
 import { errorMessage } from '../util/log.js';
 const STATS_DECIMALS = 4;
-// -------------------------------------------------------------------------
 // 2. Physics simulation pass
-// -------------------------------------------------------------------------
 export function physicsPass(run) {
     if (run.dryRun)
         return;

package/dist/consolidate/replay.d.ts

@@ -1,41 +1,9 @@
-/**
- * Replay — biologically-inspired rehearsal during consolidation.
- *
- * Hippocampal replay is internally-driven reactivation of memories during
- * slow-wave sleep: the brain picks important recent experiences and "plays
- * them back" without external input, strengthening them before they decay.
- * In McClelland's complementary-learning-systems framing, replay is also
- * how episodic memories train the neocortex (interleaved rehearsal); in
- * reward-modulated STDP, replay is gated by dopamine so rewarded
- * experiences get preferentially consolidated.
- *
- * This module implements a lightweight, deterministic analog. During each
- * `hippo sleep`, we sample N surviving memories by a priority score that
- * weighs reward feedback, emotional valence, under-rehearsal, and age —
- * then apply the same retrieval-strengthening dynamics `markRetrieved`
- * applies to real queries. The effect is that important memories stay
- * strong even when the user hasn't explicitly queried them recently.
- *
- * Distinct from the other consolidation passes:
- *   - decay: removes what's too weak
- *   - physics: moves particles in embedding space
- *   - merge: collapses near-duplicate episodics into semantics
- *   - REPLAY: picks winners and rehearses them (this file)
- */
+/** Replay: during `hippo sleep`, sample N survivors weighted by reward, valence, under-rehearsal and age, then apply the `markRetrieved` strengthening.
+ * A lightweight deterministic analog of hippocampal replay, so important memories stay strong without being queried; distinct from decay, physics and merge. */
 import { type MemoryEntry } from '../core/memory.js';
-/**
- * Priority score used to rank survivors for replay. Higher = more likely
- * to be sampled. Pure function of the entry and current time.
- */
-export declare function replayPriority(entry: MemoryEntry, now: Date): number;
-/**
- * Pick `count` memories for replay, weighted by `replayPriority`, without
- * replacement. Deterministic given the same seed.
- *
- * The sampler is weighted but not greedy — picking by priority alone would
- * always pick the top-N, which overfits. Biological replay shows both
- * preferential-for-reward AND stochastic-exploration characteristics; we
- * keep the stochastic element so adjacent survivors aren't always ignored.
- */
+/** Priority score for ranking survivors for replay (higher = more likely sampled); pure in the entry and current time. */
+export declare function replayPriority(entry: MemoryEntry, now: Date, outcomeAblated: boolean): number;
+/** Pick `count` memories for replay, weighted by `replayPriority`, without replacement; deterministic for a seed.
+ * Weighted but not greedy: always taking the top-N overfits, so a stochastic element keeps adjacent survivors in play. */
 export declare function sampleForReplay(survivors: MemoryEntry[], count: number, now: Date, seed?: number): MemoryEntry[];
 //# sourceMappingURL=replay.d.ts.map

package/dist/consolidate/replay.js

@@ -1,27 +1,5 @@
-/**
- * Replay — biologically-inspired rehearsal during consolidation.
- *
- * Hippocampal replay is internally-driven reactivation of memories during
- * slow-wave sleep: the brain picks important recent experiences and "plays
- * them back" without external input, strengthening them before they decay.
- * In McClelland's complementary-learning-systems framing, replay is also
- * how episodic memories train the neocortex (interleaved rehearsal); in
- * reward-modulated STDP, replay is gated by dopamine so rewarded
- * experiences get preferentially consolidated.
- *
- * This module implements a lightweight, deterministic analog. During each
- * `hippo sleep`, we sample N surviving memories by a priority score that
- * weighs reward feedback, emotional valence, under-rehearsal, and age —
- * then apply the same retrieval-strengthening dynamics `markRetrieved`
- * applies to real queries. The effect is that important memories stay
- * strong even when the user hasn't explicitly queried them recently.
- *
- * Distinct from the other consolidation passes:
- *   - decay: removes what's too weak
- *   - physics: moves particles in embedding space
- *   - merge: collapses near-duplicate episodics into semantics
- *   - REPLAY: picks winners and rehearses them (this file)
- */
+/** Replay: during `hippo sleep`, sample N survivors weighted by reward, valence, under-rehearsal and age, then apply the `markRetrieved` strengthening.
+ * A lightweight deterministic analog of hippocampal replay, so important memories stay strong without being queried; distinct from decay, physics and merge. */
 import { isOutcomeSlowAblated } from '../core/ablation.js';
 import { resolveConfidence } from '../core/memory.js';
 const VALENCE_WEIGHT = {
@@ -30,18 +8,13 @@ const VALENCE_WEIGHT = {
     negative: 1.5,
     critical: 2.0,
 };
-/**
- * Priority score used to rank survivors for replay. Higher = more likely
- * to be sampled. Pure function of the entry and current time.
- */
-export function replayPriority(entry, now) {
+/** Priority score for ranking survivors for replay (higher = more likely sampled); pure in the entry and current time. */
+export function replayPriority(entry, now, outcomeAblated) {
     const pos = entry.outcome_positive ?? 0;
     const neg = entry.outcome_negative ?? 0;
-    // Reward signal: neutral memories get 1, strongly-rewarded memories > 1,
-    // negative-dominated memories floor at 0.1 (so they're still eligible, just
-    // much less likely to be sampled than neutral peers). Clamp is required
-    // because sampleForReplay depends on all weights being positive.
-    const rewardSignal = isOutcomeSlowAblated()
+    // Reward signal: neutral = 1, strongly rewarded > 1, negative-dominated floors at 0.1 (still eligible, just unlikely).
+    // The clamp is required because sampleForReplay needs all weights positive.
+    const rewardSignal = outcomeAblated
         ? 1.0 // EVAL-ONLY ablation (see ablation.ts): outcome-off also silences replay's reward bias
         : Math.max(0.1, 1 + pos * 0.5 + (pos - neg) * 0.25);
     const valence = VALENCE_WEIGHT[entry.emotional_valence] ?? 1.0;
@@ -57,11 +30,7 @@ export function replayPriority(entry, now) {
     const strengthFloor = Math.max(0.1, rawStrength);
     return rewardSignal * valence * underRehearsed * idleBoost * strengthFloor;
 }
-/**
- * Deterministic 32-bit RNG (Mulberry32). Same seed → same sequence.
- * Keeps replay reproducible for tests and audit runs without bringing
- * in a random-number dependency.
- */
+/** Deterministic 32-bit RNG (Mulberry32): same seed, same sequence, so replay is reproducible without a random-number dependency. */
 function mulberry32(seed) {
     let s = seed >>> 0;
     return () => {
@@ -71,29 +40,22 @@ function mulberry32(seed) {
         return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
     };
 }
-/**
- * Pick `count` memories for replay, weighted by `replayPriority`, without
- * replacement. Deterministic given the same seed.
- *
- * The sampler is weighted but not greedy — picking by priority alone would
- * always pick the top-N, which overfits. Biological replay shows both
- * preferential-for-reward AND stochastic-exploration characteristics; we
- * keep the stochastic element so adjacent survivors aren't always ignored.
- */
+/** Pick `count` memories for replay, weighted by `replayPriority`, without replacement; deterministic for a seed.
+ * Weighted but not greedy: always taking the top-N overfits, so a stochastic element keeps adjacent survivors in play. */
 export function sampleForReplay(survivors, count, now, seed = Date.now() >>> 0) {
     if (count <= 0 || survivors.length === 0)
         return [];
     const rng = mulberry32(seed);
-    // Deliberately-marked and aged-out memories are both untrusted; rehearsing
-    // them would defeat the purpose of staleness, so derive rather than trust
-    // the stored value (it no longer carries the age-out case, see memory.ts).
+    // Deliberately-marked and aged-out memories are both untrusted and rehearsing them defeats staleness, so derive rather than trust
+    // the stored value (it no longer carries the age-out case).
     const eligible = survivors.filter((e) => resolveConfidence(e, now) !== 'stale');
     if (eligible.length === 0)
         return [];
+    const outcomeAblated = isOutcomeSlowAblated();
     const pool = eligible.map((entry, idx) => ({
         entry,
         idx,
-        weight: replayPriority(entry, now),
+        weight: replayPriority(entry, now, outcomeAblated),
     }));
     const want = Math.min(count, pool.length);
     const chosen = [];

package/dist/consolidate/run.js

@@ -1,5 +1,5 @@
 import { ftsDrift } from '../store/entry-row.js';
-import { NO_MERGE_TAGS } from '../sharing/shared.js';
+import { NO_MERGE_TAGS } from '../sharing/share.js';
 export const REPLAY_COUNT_DEFAULT = 5;
 export function keptAsWritten(entry) {
     return entry.tags.some((tag) => NO_MERGE_TAGS.has(tag));

package/dist/consolidate/sleep.d.ts

@@ -1,11 +1,4 @@
-/**
- * Consolidation engine ("Sleep") for Hippo.
- *
- * Steps:
- * 1. Decay pass  - remove entries below strength threshold
- * 2. Merge pass  - find episodic entries with high text overlap, create semantic summaries
- * 3. Stats tracking
- */
+/** Consolidation engine ("Sleep"): decay pass (drop entries below the strength threshold), merge pass (semantic summaries of overlapping episodics), stats. */
 import { type WriteBudget } from '../util/write-budget.js';
 import { type ConsolidationResult } from './run.js';
 /**

package/dist/consolidate/sleep.js

@@ -1,14 +1,7 @@
-/**
- * Consolidation engine ("Sleep") for Hippo.
- *
- * Steps:
- * 1. Decay pass  - remove entries below strength threshold
- * 2. Merge pass  - find episodic entries with high text overlap, create semantic summaries
- * 3. Stats tracking
- */
+/** Consolidation engine ("Sleep"): decay pass (drop entries below the strength threshold), merge pass (semantic summaries of overlapping episodics), stats. */
 import { evalNow } from '../core/ablation.js';
 import { canAutoDelete } from '../core/memory.js';
-import { loadAllEntries } from '../store/entry-reads.js';
+import { loadAllEntriesWithBase } from '../store/entry-reads.js';
 import { commitInChunks, memoriesBackingObjects } from '../store/delete-and-batch.js';
 import { appendConsolidationRun, loadSessionDecayContext, incrementSleepCount } from '../store/index-and-stats.js';
 import { replaceDetectedConflicts } from '../store/conflicts.js';
@@ -40,14 +33,13 @@ export async function consolidate(hippoRoot, options = {}) {
     syncFtsIndex(hippoRoot, dryRun, result);
     // Host-wide by design: per-tenant filtering would mean N runs per host and no cross-tenant dedup.
     // The api.sleep audit row tags this with the admin synthetic actor.
-    const all = loadAllEntries(hippoRoot);
+    const { entries: all, base: snapshot } = loadAllEntriesWithBase(hippoRoot);
     if (dryRun)
         for (const e of all)
             e.half_life_days = halfLife.halfLives.get(e.id) ?? e.half_life_days;
     const backingObjects = memoriesBackingObjects(hippoRoot);
     // Retirable: auto-deletable (never pinned, raw or kept for good) and not backing a first-class object.
     const retirable = (entry) => canAutoDelete(entry) && !backingObjects.has(entry.id);
-    const snapshot = new Map(structuredClone(all).map((e) => [e.id, e]));
     const config = loadConfig(hippoRoot);
     const decayOpts = sessionDecayOptions(hippoRoot, config);
     const run = {
@@ -125,10 +117,8 @@ async function flushPending(run, snapshot, budget) {
     result.removed = result.removedIds.length;
     result.dormant = pendingDormant.filter((m) => left.has(m.entry.id)).length;
 }
-// Dormant retention: a dormant memory nobody restored within
-// dormant.retentionDays is deleted for good (0 keeps them forever). Runs
-// even when dormant.enabled is off, so turning it off still ages out what
-// earlier sleeps kept.
+// Dormant retention: a dormant memory nobody restored within dormant.retentionDays is deleted for good (0 keeps forever);
+// runs even when dormant.enabled is off, so turning it off still ages out what earlier sleeps kept.
 async function expireDormant(run, budget) {
     const { config, result, dryRun } = run;
     if (!(config.dormant.retentionDays > 0))
@@ -139,9 +129,7 @@ async function expireDormant(run, budget) {
         result.details.push(`  ⌛ ${dryRun ? 'would expire' : 'expired'} ${result.dormantExpired} dormant memor${result.dormantExpired === 1 ? 'y' : 'ies'} older than ${config.dormant.retentionDays} days`);
     }
 }
-// -------------------------------------------------------------------------
 // 4. Log run
-// -------------------------------------------------------------------------
 function logRun(run, decay) {
     const { hippoRoot, now, result } = run;
     const detectedConflicts = detectConflicts(run.survivors, now, run.decayOpts, decay.rescuedIds);

package/dist/consolidate/trace.d.ts

@@ -1,10 +1,5 @@
-/**
- * Trace-layer helpers.
- *
- * A trace is a `MemoryEntry` with `layer === 'trace'` that captures an ordered
- * sequence of agent actions and their final outcome. v1 stores steps as
- * markdown in `content`; `renderTraceContent` is the canonical formatter.
- */
+/** Trace-layer helpers. A trace is a `MemoryEntry` with `layer === 'trace'`: ordered agent actions and their outcome, stored as markdown in `content`
+ * (`renderTraceContent` formats it). */
 export interface TraceStep {
     action: string;
     observation: string;
@@ -15,17 +10,7 @@ export interface TraceRecord {
     steps: TraceStep[];
     outcome: 'success' | 'failure' | 'partial';
 }
-/**
- * Render a trace record as agent-readable markdown.
- *
- * Format:
- *   Task: <task>
- *   Outcome: <outcome>
- *   Steps:
- *     1. <action>
- *        → <observation>   (omitted if observation is empty)
- *     2. ...
- */
+/** Render a trace record as agent-readable markdown: `Task:`, `Outcome:`, then numbered `Steps:` with each observation on an arrow line (omitted if empty). */
 export declare function renderTraceContent(rec: TraceRecord): string;
 /**
  * Parse a JSON string into an array of TraceStep. Throws on invalid shape.

package/dist/consolidate/trace.js

@@ -1,23 +1,8 @@
-/**
- * Trace-layer helpers.
- *
- * A trace is a `MemoryEntry` with `layer === 'trace'` that captures an ordered
- * sequence of agent actions and their final outcome. v1 stores steps as
- * markdown in `content`; `renderTraceContent` is the canonical formatter.
- */
+/** Trace-layer helpers. A trace is a `MemoryEntry` with `layer === 'trace'`: ordered agent actions and their outcome, stored as markdown in `content`
+ * (`renderTraceContent` formats it). */
 import { isJsonString, isJsonObject } from '../util/json.js';
 import { errorMessage } from '../util/log.js';
-/**
- * Render a trace record as agent-readable markdown.
- *
- * Format:
- *   Task: <task>
- *   Outcome: <outcome>
- *   Steps:
- *     1. <action>
- *        → <observation>   (omitted if observation is empty)
- *     2. ...
- */
+/** Render a trace record as agent-readable markdown: `Task:`, `Outcome:`, then numbered `Steps:` with each observation on an arrow line (omitted if empty). */
 export function renderTraceContent(rec) {
     const lines = [];
     lines.push(`Task: ${rec.task}`);

package/dist/consolidate/traces.js

@@ -11,14 +11,8 @@ import { log } from '../util/log.js';
 import { REPLAY_COUNT_DEFAULT } from './run.js';
 import { isJsonString } from '../util/json.js';
 import { DAY_MS } from '../util/time.js';
-// -------------------------------------------------------------------------
-// 1.4. Auto-promote complete sessions to traces
-// -------------------------------------------------------------------------
-//
-// For each session within the configured window that has a `session_complete`
-// event and no existing trace (idempotency via the source_session_id column),
-// render the action sequence as markdown and persist a Layer.Trace memory.
-// Traces inherit decay, search, replay, and physics from the base MemoryEntry.
+// 1.4. Auto-promote complete sessions to traces: each session in the window with a `session_complete` event and no trace (idempotent via source_session_id)
+// is rendered as markdown and persisted as a Layer.Trace memory, which inherits decay, search, replay and physics.
 export function promoteSessionTraces(run) {
     const { result } = run;
     if (run.dryRun || run.config.autoTraceCapture === false)
@@ -129,23 +123,13 @@ function traceRejected(run, trace, sessionId) {
     }
     return true;
 }
-// -------------------------------------------------------------------------
-// 1.5. Replay pass — rehearse high-value survivors
-// -------------------------------------------------------------------------
-//
-// Biologically-inspired counterpart to hippocampal replay during slow-wave
-// sleep: sample N memories weighted by outcome + valence + under-rehearsal
-// + idle time, then apply the same retrieval-strengthening `markRetrieved`
-// applies to real queries. Distinct from decay (removal), physics (motion),
-// and merge (compression) — this is the "rehearse the important stuff so
-// it doesn't fade" pass.
+// 1.5. Replay pass: rehearse high-value survivors by sampling N memories weighted by outcome, valence, under-rehearsal and idle time,
+// then applying the `markRetrieved` strengthening, so important memories don't fade.
 export function replayPass(run) {
     const { survivors, now } = run;
     const replayCount = run.config.replay?.count ?? REPLAY_COUNT_DEFAULT;
-    // EVAL-ONLY ablation (see ablation.ts): replay rehearsal IS recall
-    // strengthening (same markRetrieved dynamics), so the strengthen-off arm
-    // silences the whole pass - markRetrieved would return unmutated entries
-    // and persisting them anyway would still refresh updated_at / mirrors.
+    // EVAL-ONLY ablation (see ablation.ts): replay rehearsal is recall strengthening, so the strengthen-off arm silences the whole pass;
+    // persisting unmutated entries anyway would still refresh updated_at and mirrors.
     if (!(replayCount > 0 && survivors.length > 0 && !isRecallBoostAblated()))
         return;
     const seed = Math.floor(now.getTime() / 1000) & 0xffffffff;