hippo-memory 1.70.0 → 1.72.0

package/dist/consolidate/memory-value.js

@@ -1,23 +1,7 @@
-/**
- * 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 { strengthAblation } from '../core/ablation.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 +20,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;
@@ -69,7 +32,7 @@ export function computeMvFeatures(entry, now) {
     return {
         age_days: ageDays,
         half_life_days: entry.half_life_days,
-        strength: calculateStrength(entry, now), // clock-basis, never decayOpts — see doc comment above
+        strength: calculateStrength(entry, now, { ablation: strengthAblation() }), // clock-basis, never the production decay basis — see doc comment above
         retrieval_count: entry.retrieval_count,
         outcome_positive: pos,
         outcome_negative: neg,
@@ -77,16 +40,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 +60,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 +104,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 +114,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 +146,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

@@ -3,10 +3,10 @@ import { tokenize } from '../util/tokenize.js';
 import { jaccardMinShared, overlapPartners } from './overlap-index.js';
 import { compareEntryIdentity } from '../core/compare.js';
 import { duplicateKey, mergedText } from '../util/same-text.js';
-import { successorAfterRetirement } from './merged-row.js';
+import { successorAfterRetirement } from '../core/merged-row.js';
 import { rejectionDigest } from '../store/rejection.js';
 import { reportAuditWriteFailure } from '../store/audit.js';
-import { derivationScope, derivationPartitionKey } from '../store/recall-scope.js';
+import { derivationScope, derivationPartitionKey } from '../core/recall-scope.js';
 import { jaccardSets } from './conflicts.js';
 import { keptAsWritten } from './run.js';
 import { isReusable } from '../core/memory-quality.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/physics-pass.d.ts

@@ -1,3 +1,8 @@
+import { type PhysicsParticle } from '../core/physics.js';
+import type { MemoryEntry } from '../core/memory.js';
 import type { SleepRun } from './run.js';
-export declare function physicsPass(run: SleepRun): void;
+export declare function physicsPass(run: SleepRun, maxParticles?: number): void;
+/** Every stored particle in load order up to the cap; past it, the most recently recalled survivors (memory id breaks ties),
+ * then particles with no survivor. */
+export declare function particlesToSimulate(stored: PhysicsParticle[], entries: ReadonlyMap<string, MemoryEntry>, max?: number): PhysicsParticle[];
 //# sourceMappingURL=physics-pass.d.ts.map

package/dist/consolidate/physics-pass.js

@@ -1,12 +1,12 @@
 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;
-// -------------------------------------------------------------------------
+// Every substep is all-pairs, so one sleep moves at most this many particles; the rest keep their stored state until they are recalled.
+const SLEEP_PHYSICS_MAX_PARTICLES = 1000;
 // 2. Physics simulation pass
-// -------------------------------------------------------------------------
-export function physicsPass(run) {
+export function physicsPass(run, maxParticles = SLEEP_PHYSICS_MAX_PARTICLES) {
     if (run.dryRun)
         return;
     const { config, result } = run;
@@ -14,27 +14,45 @@ export function physicsPass(run) {
         const physicsEnabled = config.physics.enabled === true
             || (config.physics.enabled === 'auto');
         if (physicsEnabled)
-            simulateStoredParticles(run);
+            simulateStoredParticles(run, maxParticles);
     }
     catch (error) {
         result.details.push(`  ⚠️ physics simulation skipped: ${errorMessage(error)}`);
     }
 }
-function simulateStoredParticles(run) {
+function simulateStoredParticles(run, maxParticles) {
     const { result, survivors } = run;
-    const particles = loadStoredParticles(run.hippoRoot);
-    if (particles.length === 0)
+    const stored = loadStoredParticles(run.hippoRoot);
+    if (stored.length === 0)
         return;
     // Build entry lookup for property refresh
     const entryMap = new Map(survivors.map(e => [e.id, e]));
+    const particles = particlesToSimulate(stored, entryMap, maxParticles);
     refreshParticleProperties(particles, entryMap, run.now);
     const stats = simulate(particles, survivorForces(run));
     saveStoredParticles(run.hippoRoot, particles);
     result.physicsSimulated = stats.particleCount;
-    result.details.push(`  ⚛️  physics: ${stats.particleCount} particles, ` +
+    const capped = particles.length < stored.length ? ` (the ${particles.length} most recently recalled of ${stored.length})` : '';
+    result.details.push(`  ⚛️  physics: ${stats.particleCount} particles${capped}, ` +
         `avg vel ${stats.avgVelocityMagnitude.toFixed(STATS_DECIMALS)}, ` +
         `energy ${stats.energy.total.toFixed(STATS_DECIMALS)}`);
 }
+/** Every stored particle in load order up to the cap; past it, the most recently recalled survivors (memory id breaks ties),
+ * then particles with no survivor. */
+export function particlesToSimulate(stored, entries, max = SLEEP_PHYSICS_MAX_PARTICLES) {
+    if (stored.length <= max)
+        return stored;
+    const recalled = (p) => entries.get(p.memoryId)?.last_retrieved ?? '';
+    const ranked = [...stored].sort((a, b) => {
+        const [ra, rb] = [recalled(a), recalled(b)];
+        if (ra !== rb)
+            return ra < rb ? 1 : -1;
+        return a.memoryId < b.memoryId ? -1 : a.memoryId > b.memoryId ? 1 : 0;
+    });
+    const kept = new Set(ranked.slice(0, max));
+    // Load order, not rank order: the force sums run in this order, so a capped run matches an uncapped one over the same set.
+    return stored.filter((p) => kept.has(p));
+}
 function survivorForces(run) {
     // Build conflict pairs from survivors
     const conflictPairs = new Map();

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,6 @@
-/**
- * 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 { HOUR_MS } from '../util/time.js';
 import { isOutcomeSlowAblated } from '../core/ablation.js';
 import { resolveConfidence } from '../core/memory.js';
 const VALENCE_WEIGHT = {
@@ -30,38 +9,35 @@ 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) {
+// Floor keeps every weight positive for sampleForReplay; the rest scale reward and idle boosts.
+const REWARD_FLOOR = 0.1;
+const REWARD_POSITIVE_GAIN = 0.5;
+const REWARD_NET_GAIN = 0.25;
+const IDLE_BOOST_GAIN = 0.1;
+const STRENGTH_FLOOR = 0.1;
+/** 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);
+        : Math.max(REWARD_FLOOR, 1 + pos * REWARD_POSITIVE_GAIN + (pos - neg) * REWARD_NET_GAIN);
     const valence = VALENCE_WEIGHT[entry.emotional_valence] ?? 1.0;
     // Under-rehearsed memories benefit most from replay.
     const underRehearsed = 1 / (1 + (entry.retrieval_count ?? 0));
     // Idle-time boost: memories that haven't been touched recently need rehearsal more.
     const lastRetrieved = new Date(entry.last_retrieved);
     const deltaMs = now.getTime() - lastRetrieved.getTime();
-    const ageHours = Number.isFinite(deltaMs) ? Math.max(0, deltaMs / 3_600_000) : 0;
-    const idleBoost = 1 + Math.log1p(ageHours) * 0.1;
+    const ageHours = Number.isFinite(deltaMs) ? Math.max(0, deltaMs / HOUR_MS) : 0;
+    const idleBoost = 1 + Math.log1p(ageHours) * IDLE_BOOST_GAIN;
     // Weight by current strength so dead-and-decaying memories don't waste replay slots.
     const rawStrength = Number.isFinite(entry.strength) ? entry.strength : 0;
-    const strengthFloor = Math.max(0.1, rawStrength);
+    const strengthFloor = Math.max(STRENGTH_FLOOR, 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 +47,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';
 /**