hippo-memory 1.70.0 → 1.71.0

package/dist/core/memory.js

@@ -1,12 +1,10 @@
-/**
- * Core data model for Hippo memory entries.
- * Based on the strength formula from PLAN.md.
- */
-import { envLossAversionRatio } from '../util/env.js';
+/** Core data model for Hippo memory entries, based on the strength formula from PLAN.md. */
+import { DEFAULT_TENANT_ID, envLossAversionRatio } from '../util/env.js';
 import { BadRequestError } from './api-errors.js';
 import { randomUUID } from 'crypto';
 import { isDecayAblated, isOutcomeSlowAblated, isRecallBoostAblated, evalNow, } from './ablation.js';
 import { AGENT_MEMORY_TOOLS, toolSourcePrefix } from './agent-memory-tools.js';
+import { isJsonString } from '../util/json.js';
 import { DAY_MS } from '../util/time.js';
 import { ID_SUFFIX_CHARS } from '../util/token-text.js';
 export const DEFAULT_SCHEMA_FIT = 0.5;
@@ -20,56 +18,17 @@ export var Layer;
 })(Layer || (Layer = {}));
 /** Tag on a memory whose named file/symbol/script changed after it was stored. */
 export const CHURN_STALE_TAG = 'churn-stale';
-// Emotional multipliers from PLAN.md. Losses weigh ~2x equivalent gains (Lovallo-Kahneman TFAS empirics),
-// so negative is 2.0. `negative` is further scaled per-process by HIPPO_LOSS_AVERSION_RATIO
-// (env var, default 1.0; see getLossAversionRatio + applyLossAversionRatio).
-const EMOTIONAL_MULTIPLIERS = {
+// Losses weigh ~2x gains (Lovallo-Kahneman), so negative is 2.0; HIPPO_LOSS_AVERSION_RATIO scales it per process.
+export const EMOTIONAL_MULTIPLIERS = {
     neutral: 1.0,
     positive: 1.0,
     negative: 2.0, // error-tagged
     critical: 2.0,
 };
-/**
- * Module-level lazy-cached read of HIPPO_LOSS_AVERSION_RATIO.
- *
- * `calculateStrength` is called per-entry inside hot recall loops
- * (api.ts/consolidate.ts/search.ts), so a per-call `process.env` lookup
- * would multiply N entries by M recalls of lookup cost. Lazy module-cache
- * reads the env ONCE on first call and memoizes for the process lifetime.
- * Test isolation via `_resetLossAversionRatioCacheForTests()` below.
- */
-/**
- * Minimum acceptable ratio. Below this, the negative multiplier
- * (2.0 * ratio) becomes small enough that calculateStrength * decay can fall
- * below `DECAY_THRESHOLD = 0.05` in `src/consolidate.ts:146`, which would
- * permanently delete non-pinned error-tagged memories on the next sleep
- * cycle. 0.5 is chosen as the floor because (a) it recovers the pre-calibration
- * effective multiplier (2.0 * 0.5 = 1.0 + the negative premium, i.e. 1.5x
- * the pre-calibration default), and (b) below this the user is asking for LESS
- * loss aversion than has ever shipped — that's outside the supported
- * tuning range.
- */
+// A lower ratio can drop an error-tagged memory under sleep's DECAY_THRESHOLD (src/consolidate/decay.ts),
+// so values below it fall back to 1.0.
 const LOSS_AVERSION_RATIO_MIN = 0.5;
-/**
- * Validation policy:
- *   - Valid: finite numbers >= 0.5.
- *   - Invalid (silent fallback to 1.0): empty string, non-numeric,
- *     numbers below 0.5 (including 0 and negatives), NaN, +/-Infinity.
- *     Silent because opt-in env vars should not crash production recall
- *     on a typo.
- *
- * Why the 0.5 floor and not 0:
- *   - Rejecting only `0` leaves the same silent data-loss surface for any ratio
- *     below ~0.025 (and worse for aged memories, where even ratio=0.25
- *     can produce strength < DECAY_THRESHOLD = 0.05 in consolidate.ts).
- *     Floor at the pre-calibration equivalent (0.5) so the env var's tuning
- *     range never crosses into the deletion regime.
- *   - Users wanting LESS loss aversion than the pre-calibration 1.5 multiplier
- *     should reconsider the design intent (the calibration was
- *     toward MORE loss aversion, not less). If a future use case
- *     genuinely needs ratio < 0.5, the right path is a separate
- *     `HIPPO_NEGATIVE_MULTIPLIER` env override.
- */
+// Read once: calculateStrength runs per entry inside hot loops (src/api, src/consolidate, src/search).
 let _lossAversionRatioCache;
 function getLossAversionRatio() {
     if (_lossAversionRatioCache !== undefined)
@@ -80,8 +39,6 @@ function getLossAversionRatio() {
         return 1.0;
     }
     const parsed = Number(raw);
-    // Finite + >= 0.5 floor. Anything below 0.5 silently falls back to 1.0
-    // to avoid the consolidation-deletion vector (see JSDoc above).
     if (!Number.isFinite(parsed) || parsed < LOSS_AVERSION_RATIO_MIN) {
         _lossAversionRatioCache = 1.0;
         return 1.0;
@@ -89,39 +46,17 @@ function getLossAversionRatio() {
     _lossAversionRatioCache = parsed;
     return parsed;
 }
-/**
- * Test-only helper. Tests that mutate `process.env.HIPPO_LOSS_AVERSION_RATIO`
- * MUST call this in BOTH `beforeEach` AND `afterEach`:
- *   - beforeEach: clear any stale cache from a previous test before setting
- *     the env var for this test.
- *   - afterEach: clear the cache so the next test (which may not set the env
- *     var) reads the clean default instead of this test's value.
- * See `tests/emotional-multipliers.test.ts` for the pattern.
- */
+/** Test-only: a test that sets HIPPO_LOSS_AVERSION_RATIO calls this in beforeEach and afterEach (tests/emotional-multipliers.test.ts). */
 export function _resetLossAversionRatioCacheForTests() {
     _lossAversionRatioCache = undefined;
 }
-/**
- * Apply the loss-aversion ratio scalar to the `negative` multiplier ONLY.
- * Other valences (positive, critical, neutral) pass through unchanged.
- * `critical` is deliberately NOT scaled, so the calibration only touches the
- * specific empirical claim (TFAS 2x losses-vs-gains).
- */
-function applyLossAversionRatio(valence, baseMultiplier) {
+/** Scales only the `negative` multiplier; `critical` stays unscaled so the knob moves just the losses-vs-gains claim. */
+export function applyLossAversionRatio(valence, baseMultiplier) {
     if (valence !== 'negative')
         return baseMultiplier;
     return baseMultiplier * getLossAversionRatio();
 }
-/**
- * Compute the reward factor from cumulative outcome counts.
- *
- *   reward_ratio  = (positive - negative) / (positive + negative + 1)
- *   reward_factor = 1 + 0.5 * reward_ratio
- *
- * Range: (0.5, 1.5). Neutral (no outcomes) returns 1.0.
- * Modulates effective half-life: memories with consistent positive outcomes
- * decay slower; consistent negative outcomes decay faster.
- */
+/** 1 + REWARD_SLOPE * (pos - neg) / (pos + neg + 1), in (0.5, 1.5), 1.0 with no outcomes; it scales the effective half-life. */
 export function calculateRewardFactor(entry) {
     // EVAL-ONLY ablation (see ablation.ts): the slow outcome channel.
     if (isOutcomeSlowAblated())
@@ -134,65 +69,41 @@ export function calculateRewardFactor(entry) {
     return 1 + REWARD_SLOPE * ratio;
 }
 /** Bad marks alone never push a memory under sleep's 0.05 retire line; supersede is the hard correction. */
-const MAX_WRONG_HALVINGS = 3;
-// Shared by calculateStrength and strengthSql so the two cannot drift.
-const DECAY_BASE = 0.5;
-const REWARD_SLOPE = 0.5;
-const RETRIEVAL_BOOST_SLOPE = 0.1;
-const SQL_DEFAULT_HALF_LIFE_DAYS = 7;
-const UNIX_EPOCH_JULIAN_DAY = 2440587.5;
-/**
- * Net wrongness: bad outcome marks past good ones, never below zero.
- * Strength halves per unit (capped at 3) and recall stops strengthening
- * the memory, so a correction outranks pinning, error tags and heavy recall.
- */
+export const MAX_WRONG_HALVINGS = 3;
+// Shared by calculateStrength and strengthSql (src/store/rule-sql.ts) so the two cannot drift.
+export const DECAY_BASE = 0.5;
+export const REWARD_SLOPE = 0.5;
+export const RETRIEVAL_BOOST_SLOPE = 0.1;
+/** Bad outcome marks past good ones, floored at zero; each halves strength and stops recall strengthening, so a correction outranks pinning. */
 export function netWrong(entry) {
     if (isOutcomeSlowAblated() || isDecayAblated())
         return 0;
     return Math.max(0, (entry.outcome_negative ?? 0) - (entry.outcome_positive ?? 0));
 }
-/**
- * Calculate current strength at a given time.
- * strength(t) = base_strength * decay * retrieval_boost * emotional_multiplier
- *
- * Decay basis modes:
- * - clock: classic wall-clock decay (daysSince / halfLife)
- * - session: decay by sleep cycles instead of days (sessionsSince / halfLife)
- * - adaptive: wall-clock decay with half-life scaled by session frequency
- *
- * Pinned memories skip time decay; being marked wrong still fades them (netWrong).
- */
+/** Strength at `now` = decay * retrieval boost * emotional multiplier, clamped to [0, 1]; the basis modes are on DecayOptions.
+ *  Pinned memories skip time decay, but being marked wrong still fades them (netWrong). */
 export function calculateStrength(entry, 
-// evalNow(): the real clock unless HIPPO_FAKE_NOW is set (eval-only,
-// simulated-time protocols; see ablation.ts). Explicit `now` always wins.
+// evalNow() is the real clock unless HIPPO_FAKE_NOW is set (eval-only); an explicit `now` wins.
 now = evalNow(), options = {}) {
     // Being marked wrong outranks every shield: pinning, error tags, heavy recall.
     const wrongPenalty = Math.pow(DECAY_BASE, Math.min(netWrong(entry), MAX_WRONG_HALVINGS));
     if (entry.pinned)
         return wrongPenalty;
-    // EVAL-ONLY ablation (see ablation.ts): anchor decay at CREATION, so clock resets persisted by PRIOR
-    // unflagged runs cannot leak strengthening into an ablated arm. Prior-run half_life increments are
-    // NOT reconstructed - see the ablation.ts caveat (fresh stores per arm).
+    // EVAL-ONLY ablation (see ablation.ts): anchor decay at creation so clock resets from earlier unflagged runs cannot leak in.
     const lastRetrieved = new Date(isRecallBoostAblated() ? entry.created : entry.last_retrieved);
     const daysSince = (now.getTime() - lastRetrieved.getTime()) / DAY_MS;
-    // Reward-proportional half-life modulation
     const rewardFactor = calculateRewardFactor(entry);
     const effectiveHalfLife = entry.half_life_days * rewardFactor;
     // Guard: zero half-life causes 0/0 = NaN in the exponent
     if (effectiveHalfLife <= 0)
         return 0.0;
     const decayExponent = decayExponentFor(options, daysSince, effectiveHalfLife);
-    // EVAL-ONLY ablation (see ablation.ts): decay term := 1. NOTE the [0,1]
-    // clamp below then caps retrievalBoost at baseline - see ablation.ts
-    // formula note.
+    // EVAL-ONLY ablation (see ablation.ts): decay := 1, so the [0,1] clamp below caps the boost at baseline.
     const decay = isDecayAblated() ? 1.0 : Math.pow(DECAY_BASE, decayExponent);
     const retrievalBoost = retrievalBoostFor(entry);
-    // Emotional multiplier. HIPPO_LOSS_AVERSION_RATIO scales the negative one ONLY; the lazy
-    // module cache makes this one lookup + one multiply, not a per-call process.env read.
     const baseMultiplier = EMOTIONAL_MULTIPLIERS[entry.emotional_valence] ?? 1.0;
     const emotionalMultiplier = applyLossAversionRatio(entry.emotional_valence, baseMultiplier);
     const raw = decay * retrievalBoost * emotionalMultiplier;
-    // Clamp to [0, 1] with NaN guard
     const clamped = Math.min(1.0, Math.max(0.0, raw));
     return Number.isFinite(clamped) ? clamped * wrongPenalty : 0.0;
 }
@@ -200,8 +111,7 @@ function decayExponentFor(options, daysSince, halfLifeDays) {
     let effectiveHalfLife = halfLifeDays;
     const basis = options.decayBasis ?? 'clock';
     if (basis === 'session') {
-        // Decay by session count: each sleep cycle = 1 "day" in the decay formula.
-        // Estimate sessions since last retrieval from wall-clock time and avg interval.
+        // Each sleep cycle counts as one "day"; sessions since last retrieval are estimated from wall time and the average interval.
         const avgInterval = options.avgSessionIntervalDays ?? 1;
         const sessionsSince = avgInterval > 0 ? Math.max(0, daysSince / avgInterval) : daysSince;
         return sessionsSince / effectiveHalfLife;
@@ -214,44 +124,14 @@ function decayExponentFor(options, daysSince, halfLifeDays) {
         }
         return daysSince / effectiveHalfLife;
     }
-    // clock: classic wall-clock decay
     return daysSince / effectiveHalfLife;
 }
-// Retrieval boost: 1 + 0.1 * log2(retrieval_count + 1). EVAL-ONLY ablation (see ablation.ts) neutralizes
-// the READ side too, so counts written before the flag cannot leak strengthening into an ablated arm.
+// EVAL-ONLY ablation (see ablation.ts) neutralizes the read side too, so counts written before the flag cannot leak in.
 function retrievalBoostFor(entry) {
     return isRecallBoostAblated() || netWrong(entry) > 0
         ? 1.0
         : 1 + RETRIEVAL_BOOST_SLOPE * Math.log2(entry.retrieval_count + 1);
 }
-/** calculateStrength's clock-basis formula as SQL over `memories` columns, flags and multipliers baked in; keep in step.
- *  An unparseable date scores NULL here and 0 in JS, so sums agree. */
-export function strengthSql(now) {
-    const num = (n) => (Number.isInteger(n) ? n.toFixed(1) : String(n));
-    const pos = 'COALESCE(outcome_positive, 0)';
-    const neg = 'COALESCE(outcome_negative, 0)';
-    const wrong = isOutcomeSlowAblated() || isDecayAblated() ? '0' : `MAX(0, ${neg} - ${pos})`;
-    const reward = isOutcomeSlowAblated()
-        ? '1.0'
-        : `(CASE WHEN ${pos} = 0 AND ${neg} = 0 THEN 1.0 ELSE 1.0 + ${REWARD_SLOPE} * (${pos} - ${neg}) / (${pos} + ${neg} + 1.0) END)`;
-    const halfLife = `(COALESCE(half_life_days, ${SQL_DEFAULT_HALF_LIFE_DAYS}) * ${reward})`;
-    const anchor = isRecallBoostAblated() ? 'created' : 'last_retrieved';
-    const nowJulian = num(now.getTime() / DAY_MS + UNIX_EPOCH_JULIAN_DAY);
-    const decay = isDecayAblated() ? '1.0' : `pow(${DECAY_BASE}, (${nowJulian} - julianday(${anchor})) / ${halfLife})`;
-    const boost = isRecallBoostAblated()
-        ? '1.0'
-        : `(CASE WHEN ${wrong} > 0 THEN 1.0 ELSE 1.0 + ${RETRIEVAL_BOOST_SLOPE} * log2(COALESCE(retrieval_count, 0) + 1) END)`;
-    const valences = /* SAFETY: a Record keyed by EmotionalValence */ Object.keys(EMOTIONAL_MULTIPLIERS);
-    const emotion = `(CASE COALESCE(emotional_valence, 'neutral') ${valences
-        .map((v) => `WHEN '${v}' THEN ${num(applyLossAversionRatio(v, EMOTIONAL_MULTIPLIERS[v]))}`)
-        .join(' ')} ELSE 1.0 END)`;
-    const penalty = `pow(${DECAY_BASE}, MIN(${wrong}, ${MAX_WRONG_HALVINGS}))`;
-    return `(CASE WHEN pinned THEN ${penalty} WHEN ${halfLife} <= 0 THEN 0.0
-    ELSE MIN(1.0, MAX(0.0, ${decay} * ${boost} * ${emotion})) * ${penalty} END)`;
-}
-/**
- * Derive half-life based on signals, as per PLAN.md table.
- */
 const HIGH_SCHEMA_FIT = 0.7;
 const HIGH_FIT_HALF_LIFE_FACTOR = 1.5;
 const LOW_SCHEMA_FIT = 0.3;
@@ -261,35 +141,25 @@ const TAG_FIT_WEIGHT = 0.6;
 const CONTENT_FIT_WEIGHT = 0.4;
 const CONTENT_TOKEN_SHARE_MIN = 0.2;
 const CONTENT_ENOUGH_FRACTION = 0.1;
+// An error is worth remembering longer than a neutral note (PLAN.md half-life table).
+const ERROR_TAG_HALF_LIFE_FACTOR = 2;
+// Each retrieval lengthens the half-life by this many days (PLAN.md).
+const RETRIEVAL_HALF_LIFE_GAIN_DAYS = 2;
+/** The base half-life scaled by the PLAN.md signals: an error tag, and high or low schema fit. */
 export function deriveHalfLife(base, entry) {
     let hl = base;
-    // Error-tagged: 2x half-life
     if (entry.tags?.includes('error')) {
-        hl *= 2;
+        hl *= ERROR_TAG_HALF_LIFE_FACTOR;
     }
-    // High schema fit: consolidates faster (1.5x)
     if (entry.schema_fit !== undefined && entry.schema_fit > HIGH_SCHEMA_FIT) {
         hl *= HIGH_FIT_HALF_LIFE_FACTOR;
     }
-    // Low schema fit: decay faster (0.5x)
     if (entry.schema_fit !== undefined && entry.schema_fit < LOW_SCHEMA_FIT) {
         hl *= LOW_FIT_HALF_LIFE_FACTOR;
     }
     return hl;
 }
-/**
- * Apply outcome feedback to a memory entry.
- *
- * Increments outcome_positive or outcome_negative counters.
- * The reward factor in calculateStrength() uses these counts to
- * continuously modulate the effective half-life:
- *   reward_ratio  = (pos - neg) / (pos + neg + 1)
- *   reward_factor = 1 + 0.5 * reward_ratio    // range (0.5, 1.5)
- *   effective_hl  = half_life_days * reward_factor
- *
- * No fixed half-life delta. Decay rate adjusts proportionally to
- * cumulative reward signal, inspired by R-STDP in spiking networks.
- */
+/** Counts the outcome; calculateStrength turns the counts into a reward factor on the half-life, so there is no fixed delta here. */
 export function applyOutcome(entry, good) {
     const updated = {
         ...entry,
@@ -307,17 +177,17 @@ export function entryAfterOutcome(entry, good) {
         return updated;
     return { ...updated, tags: updated.tags.filter((t) => t !== CHURN_STALE_TAG) };
 }
-/**
- * Generate a random memory ID using crypto.randomUUID().
- */
+/** A new id: `prefix_` plus the first ID_SUFFIX_CHARS hex characters of a random UUID. */
 export function generateId(prefix = 'mem') {
     return `${prefix}_${randomUUID().replace(/-/g, '').slice(0, ID_SUFFIX_CHARS)}`;
 }
+// Days without a retrieval before trust lapses; pinned and verified rows are exempt by policy.
+const AGED_OUT_AFTER_DAYS = 30;
 function isAgedOut(entry, now) {
     if (entry.pinned || entry.confidence === 'verified')
         return false;
     const lastRetrieved = new Date(entry.last_retrieved);
-    return (now.getTime() - lastRetrieved.getTime()) / DAY_MS > 30;
+    return (now.getTime() - lastRetrieved.getTime()) / DAY_MS > AGED_OUT_AFTER_DAYS;
 }
 export function confidenceFacets(entry, now = evalNow()) {
     return facetsOf(entry, now);
@@ -325,8 +195,7 @@ export function confidenceFacets(entry, now = evalNow()) {
 export function facetsOf(entry, now) {
     return { tier: entry.confidence, agedOut: isAgedOut(entry, now) };
 }
-// `warn` covers exactly the rows the old collapsed-value rule did: an aged-out row
-// used to read 'stale', so warning on it separately keeps the same set.
+// An aged-out row warns on its own, since its stored tier alone would hide it.
 export function confidenceLabel(entry, now = evalNow()) {
     const { tier, agedOut } = confidenceFacets(entry, now);
     return {
@@ -334,29 +203,16 @@ export function confidenceLabel(entry, now = evalNow()) {
         warn: agedOut || tier === 'stale' || tier === 'inferred',
     };
 }
-/**
- * Resolve the effective confidence for a memory entry.
- * If the entry has not been retrieved in 30+ days and is not 'verified',
- * returns 'stale'. Otherwise returns the stored confidence value.
- */
+/** The stored confidence, or 'stale' once the entry is aged out (not retrieved for AGED_OUT_AFTER_DAYS; pinned and verified exempt). */
 export function resolveConfidence(entry, now = evalNow()) {
     return isAgedOut(entry, now) ? 'stale' : entry.confidence;
 }
-/**
- * Base half-life for a new memory, in days, before `deriveHalfLife`'s
- * write-time multipliers. 365 because 7 days lost the current fact far more
- * often, and 730 days or no decay did no better. `hippo sleep` moves memories still
- * on an older base (src/consolidate/half-life-migration.ts).
- */
+/** Base half-life in days before deriveHalfLife's multipliers: 365 because 7 lost the current fact far more often and 730 did no better.
+ *  `hippo sleep` moves memories still on an older base (src/consolidate/half-life-migration.ts). */
 export const DEFAULT_HALF_LIFE_DAYS = 365;
 export const COMPACTION_MEMORY_TAG = 'compaction-memory';
 export const COMPACTION_SOURCE_PREFIX = 'compaction:';
 export const KEEP_PAIRS = AGENT_MEMORY_TOOLS.map((t) => ({ tag: t.tag, sourcePrefix: toolSourcePrefix(t.id) }));
-const sqlText = (s) => `'${s.replace(/'/g, "''")}'`;
-// json_each matches the tag as a whole element; substr, not LIKE, keeps the prefix case-sensitive like startsWith.
-const keepPairSql = (p) => `(COALESCE(superseded_by, '') = '' AND EXISTS (SELECT 1 FROM json_each(CASE WHEN json_valid(tags_json) THEN tags_json ELSE '[]' END) WHERE value = ${sqlText(p.tag)}) AND substr(source, 1, ${p.sourcePrefix.length}) = ${sqlText(p.sourcePrefix)})`;
-// Pinned and kept rows stay (a superseded row is not kept: its successor carries the tag and source); raw rows leave only through archiveRawMemory. The SQL twin guards the DELETE itself.
-export const AUTO_DELETABLE_SQL = `pinned = 0 AND kind != 'raw'${KEEP_PAIRS.map((p) => ` AND NOT ${keepPairSql(p)}`).join('')}`;
 export function isKeptForGood(entry) {
     return !entry.superseded_by && KEEP_PAIRS.some((p) => entry.tags.includes(p.tag) && entry.source.startsWith(p.sourcePrefix));
 }
@@ -403,9 +259,8 @@ export function createMemory(content, options = {}) {
         scope: options.scope ?? null,
         owner: options.owner ?? null,
         artifact_ref: options.artifact_ref ?? null,
-        tenantId: options.tenantId ?? 'default',
+        tenantId: options.tenantId ?? DEFAULT_TENANT_ID,
     };
-    // Recalculate strength with the emotional multiplier applied
     entry.strength = calculateStrength(entry);
     return entry;
 }
@@ -433,21 +288,13 @@ export function createSuccessor(old, content, opts) {
         baseHalfLifeDays: opts.baseHalfLifeDays,
     });
     // A legacy null origin has nothing to carry, so the store stamps it from its own location.
-    if (typeof old.origin_project === 'string') {
+    if (isJsonString(old.origin_project)) {
         next.origin_project = old.origin_project;
     }
     return next;
 }
-/**
- * Compute how well new content fits existing knowledge patterns.
- * Returns 0..1 where:
- *   >0.7 = high fit (consistent with existing knowledge, consolidates faster)
- *   0.3-0.7 = moderate fit
- *   <0.3 = novel (doesn't match existing patterns, decays faster if unused)
- *
- * Uses tag overlap (always available) weighted by how common each tag is.
- * Rare shared tags signal stronger schema fit than common ones.
- */
+/** How well new content fits existing knowledge, 0..1: above 0.7 consolidates faster, below 0.3 is novel and decays faster if unused.
+ *  Tags shared with existing memories count by rarity (a rare shared tag fits more), plus content-token overlap. */
 export function computeSchemaFit(content, tags, existingEntries) {
     const tagCounts = new Map();
     for (const entry of existingEntries) {
@@ -464,10 +311,10 @@ function significantTokens(text) {
 export function schemaFitFrom(content, tags, source) {
     const N = source.rows;
     if (N === 0)
-        return 0.5; // no schema yet, neutral
+        return DEFAULT_SCHEMA_FIT;
     const tagFreq = source.tagCounts;
     if (tags.length === 0 && tagFreq.size === 0)
-        return 0.5;
+        return DEFAULT_SCHEMA_FIT;
     // Tag overlap, weighted so a shared rare tag counts for more than a shared common one.
     let weightedOverlap = 0;
     let totalWeight = 0;
@@ -509,26 +356,8 @@ function inferValence(tags) {
         return 'positive';
     return 'neutral';
 }
-/**
- * Update retrieval metadata on entries that were returned by a search.
- * Returns the mutated copies (caller must persist to disk).
- *
- * EVAL-ONLY ablation (see ablation.ts): with HIPPO_ABLATE_RECALL_BOOST set,
- * this returns the entries UNMUTATED - neutralizing all three strengthening
- * sub-effects (clock reset, retrieval_count, half-life increment) at the
- * single shared write site. The entries (not an empty array) must be
- * returned because callers derive `last_retrieval_ids` from the return
- * value, and a later `hippo outcome --good/--bad` targets those ids - an
- * empty return would silently co-ablate the outcome channel in the
- * strengthen-off arm. PERSISTENCE is gated separately at
- * each persisting caller (CLI recall, api context, MCP recall/context,
- * consolidation replay): writeEntry on identical rows still refreshes
- * updated_at, rewrites mirrors, and marks DAG parents dirty,
- * so those write loops skip under the flag.
- * The default `now` honors HIPPO_FAKE_NOW (simulated-time protocols).
- */
-// Confidence is deliberately absent below: it is an epistemic tier, not a
-// recency signal, and a stored 'stale' is always a deliberate mark.
+/** Returns copies with the retrieval count, clock and half-life updated; the caller persists them.
+ *  Under HIPPO_ABLATE_RECALL_BOOST (eval-only) the entries come back unchanged, not empty, since callers derive last_retrieval_ids from them. */
 export function markRetrieved(entries, now = evalNow()) {
     if (isRecallBoostAblated())
         return entries;
@@ -536,12 +365,13 @@ export function markRetrieved(entries, now = evalNow()) {
         if (e.superseded_by)
             return e;
         const wrong = netWrong(e) > 0;
+        // Confidence stays untouched: it is an epistemic tier, not a recency signal.
         const updated = {
             ...e,
             retrieval_count: e.retrieval_count + 1,
+            // A wrong memory keeps both, since last_retrieved is the decay anchor.
             last_retrieved: wrong ? e.last_retrieved : now.toISOString(),
-            // +2 days half-life per retrieval (PLAN.md); a wrong memory keeps both, since last_retrieved is the decay anchor
-            half_life_days: wrong ? e.half_life_days : e.half_life_days + 2,
+            half_life_days: wrong ? e.half_life_days : e.half_life_days + RETRIEVAL_HALF_LIFE_GAIN_DAYS,
         };
         updated.strength = calculateStrength(updated, now);
         return updated;

package/dist/core/package-root.d.ts

@@ -0,0 +1,3 @@
+/** The package folder: it holds package.json, bin/ and dist-ui/. The same two steps up from src/core and from dist/core. */
+export declare const PACKAGE_ROOT: string;
+//# sourceMappingURL=package-root.d.ts.map

package/dist/core/package-root.js

@@ -0,0 +1,5 @@
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+/** The package folder: it holds package.json, bin/ and dist-ui/. The same two steps up from src/core and from dist/core. */
+export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+//# sourceMappingURL=package-root.js.map

package/dist/core/physics-config.d.ts

@@ -1,7 +1,4 @@
-/**
- * Physics engine configuration for Hippo memory-as-physics.
- * All constants are tunable; defaults calibrated for ~500 memory corpus.
- */
+/** Physics engine configuration for Hippo memory-as-physics. All constants are tunable; defaults calibrated for ~500 memory corpus. */
 export interface PhysicsConfig {
     /** Use physics scoring when embeddings available. 'auto' = yes if embeddings exist. */
     enabled: boolean | 'auto';

package/dist/core/physics-config.js

@@ -1,12 +1,7 @@
-/**
- * Physics engine configuration for Hippo memory-as-physics.
- * All constants are tunable; defaults calibrated for ~500 memory corpus.
- */
+/** Physics engine configuration for Hippo memory-as-physics. All constants are tunable; defaults calibrated for ~500 memory corpus. */
 export const DEFAULT_PHYSICS_CONFIG = {
-    // Off by default: the paired ablation (benchmarks/physics-ablation/) found
-    // physics worse than classic hybrid on every metric, CI excluding zero
-    // (MRR 0.68 vs 0.84, R@5 74% vs 84%). Opt in with physics.enabled 'auto'
-    // or true.
+    // Off by default: the paired ablation (benchmarks/physics-ablation/) found physics worse than classic hybrid on every metric, CI excluding zero
+    // (MRR 0.68 vs 0.84, R@5 74% vs 84%). Opt in with physics.enabled 'auto' or true.
     enabled: false,
     G_query: 2.0,
     G_memory: 0.01,

package/dist/core/physics.d.ts

@@ -1,14 +1,6 @@
-/**
- * Memory-as-Physics engine for Hippo.
- *
- * Pure math module: forces, Velocity Verlet integration, physics-based scoring,
- * and cluster amplification. No I/O — all state is passed in and returned.
- *
- * Memories are particles on the unit hypersphere in embedding space (384-dim).
- * Forces act on them: query gravity (retrieval), inter-memory attraction,
- * conflict repulsion, and drag (consolidation). Nearby high-scoring memories
- * amplify each other via constructive interference.
- */
+/** Memory-as-Physics engine: pure math (forces, Velocity Verlet integration, physics-based scoring, cluster amplification), no I/O.
+ * Memories are particles on the unit hypersphere in embedding space (384-dim); query gravity, attraction, conflict repulsion and drag act on them,
+ * and nearby high-scoring memories amplify each other. */
 import { type EmotionalValence } from './memory.js';
 import type { PhysicsConfig } from './physics-config.js';
 export interface PhysicsParticle {
@@ -51,42 +43,16 @@ export declare function vecClampMagnitude(v: number[], maxMag: number): number[]
 export declare function computeMass(strength: number, retrievalCount: number): number;
 export declare function computeCharge(valence: EmotionalValence): number;
 export declare function computeTemperature(ageDays: number, temperatureDecay: number): number;
-/**
- * Query gravity (retrieval-time, virtual — does not update position).
- * Returns scalar force magnitude for ranking.
- *
- * F_query(i) = G_Q * mass(i) * max(0, cosine(pos_i, query))^2
- */
+/** Query gravity (retrieval-time, virtual: does not move the particle): scalar ranking magnitude F = G_Q * mass * max(0, cosine(pos, query))^2. */
 export declare function queryGravityMagnitude(particle: PhysicsParticle, queryEmbedding: number[], G_query: number): number;
-/**
- * Momentum bonus: how aligned is the particle's velocity with the query direction?
- * Returns a value in [0, 1].
- */
+/** Momentum bonus in [0, 1]: how aligned the particle's velocity is with the query direction. */
 export declare function velocityAlignmentBonus(particle: PhysicsParticle, queryEmbedding: number[]): number;
-/**
- * Inter-memory attraction force vector (consolidation-time).
- * Attractive force from particle j on particle i.
- *
- * F_attract(i,j) = G_M * m_i * m_j * max(0, cosine(i,j))^3 * direction(j→i in embedding space)
- *
- * Direction is computed as the component of (pos_j - pos_i) that lies tangent to the
- * unit sphere at pos_i (since we normalize positions back to the sphere after integration).
- */
-export declare function attractionForce(pi: PhysicsParticle, pj: PhysicsParticle, G_memory: number): number[];
-/**
- * Conflict repulsion force vector (consolidation-time).
- * Repulsive force pushing i away from j.
- *
- * F_repel(i,j) = K_R * m_i * m_j / max(0.01, cosine_distance(i,j))^2
- * where cosine_distance = 1 - cosine_similarity
- */
+/** Attraction force on particle i from j (consolidation-time): G_M m_i m_j max(0, cosine)^3, directed along (pos_j - pos_i) projected tangent to the unit
+ * sphere at pos_i (positions are re-normalized to the sphere after integration). Adds into `out` (a fresh zero vector by default) using `diff` as scratch. */
+export declare function attractionForce(pi: PhysicsParticle, pj: PhysicsParticle, G_memory: number, out?: number[], diff?: number[]): number[];
+/** Conflict repulsion on i away from j (consolidation-time): K_R * m_i * m_j / max(0.01, cosine_distance)^2, where cosine_distance = 1 - cosine_similarity. */
 export declare function repulsionForce(pi: PhysicsParticle, pj: PhysicsParticle, K_repulsion: number): number[];
-/**
- * Drag force vector (consolidation-time).
- * F_drag(i) = -drag * velocity(i) / max(1, effective_half_life(i))
- *
- * effectiveHalfLife should be passed in from the memory's current half_life_days.
- */
+/** Drag force (consolidation-time): -drag * velocity / max(1, effectiveHalfLife), with effectiveHalfLife from the memory's current half_life_days. */
 export declare function dragForce(particle: PhysicsParticle, drag: number, effectiveHalfLife: number): number[];
 export interface ForceContext {
     /** Map of memory ID -> list of conflicting memory IDs */
@@ -95,26 +61,14 @@ export interface ForceContext {
     halfLives: Map<string, number>;
     config: PhysicsConfig;
 }
-/**
- * Run the full physics simulation for one sleep cycle.
- * Mutates particles in place. Returns simulation statistics.
- */
+/** Full physics simulation for one sleep cycle; mutates particles in place and returns simulation statistics. */
 export declare function simulate(particles: PhysicsParticle[], ctx: ForceContext): SimulationStats;
 export declare function computeSystemEnergy(particles: PhysicsParticle[], G_memory: number): SystemEnergy;
-/**
- * Score all particles against a query embedding using physics-based ranking.
- * Does NOT modify particle positions (virtual force computation).
- */
+/** Scores all particles against a query embedding; virtual force computation, so it does NOT modify particle positions. */
 export declare function physicsScore(particles: PhysicsParticle[], queryEmbedding: number[], config: PhysicsConfig, 
-/** Cross-ingest-stable tie key per memoryId (typically the memory's
- *  content, supplied by the caller which has entries in scope). Without
- *  it ties fall to memoryId -- per-instance only, which lets the
- *  cluster_top_k amplification set vary across fresh ingests. */
+/** Cross-ingest-stable tie key per memoryId (typically the memory content, from a caller with entries in scope); without it ties fall to memoryId,
+ *  which is per-instance only and lets the cluster_top_k amplification set vary across fresh ingests. */
 tieKeyOf?: (memoryId: string) => string): ScoredPhysicsResult[];
-/**
- * Nudge a particle's position toward (good outcome) or away from (bad outcome)
- * the query embedding. Respects temperature: new memories respond more.
- * Mutates particle in place.
- */
+/** Nudges a particle toward (good outcome) or away from (bad outcome) the query embedding; new memories respond more (temperature). Mutates in place. */
 export declare function applyOutcomeFeedback(particle: PhysicsParticle, queryEmbedding: number[], good: boolean, feedbackAlpha: number): void;
 //# sourceMappingURL=physics.d.ts.map