hippo-memory 1.72.0 → 2.1.0

package/dist/core/memory.js

@@ -17,6 +17,8 @@ export var Layer;
     Layer["Trace"] = "trace";
 })(Layer || (Layer = {}));
 export const MEMORY_KINDS = ['raw', 'distilled', 'superseded', 'archived'];
+/** Named dag_level values; level 0 is a raw leaf. */
+export const DAG_LEVEL = { extracted: 1, topic: 2, entity: 3 };
 /** Tag on a memory whose named file/symbol/script changed after it was stored. */
 export const CHURN_STALE_TAG = 'churn-stale';
 // Losses weigh ~2x gains (Lovallo-Kahneman), so negative is 2.0; HIPPO_LOSS_AVERSION_RATIO scales it per process.
@@ -47,17 +49,25 @@ function getLossAversionRatio() {
     _lossAversionRatioCache = parsed;
     return parsed;
 }
-/** Test-only: a test that sets HIPPO_LOSS_AVERSION_RATIO calls this in beforeEach and afterEach (tests/emotional-multipliers.test.ts). */
+/**
+ * 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;
 }
-/** Scales only the `negative` multiplier; `critical` stays unscaled so the knob moves just the losses-vs-gains claim. */
+/**
+ * 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();
 }
-/** 1 + REWARD_SLOPE * (pos - neg) / (pos + neg + 1), in (0.5, 1.5), 1.0 with no outcomes; it scales the effective half-life. */
+/**
+ * 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, ablation = NO_STRENGTH_ABLATION) {
     // EVAL-ONLY ablation (see ablation.ts): the slow outcome channel.
     if (ablation.outcomeSlow)
@@ -75,13 +85,18 @@ export const MAX_WRONG_HALVINGS = 3;
 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. */
+/**
+ * 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, ablation = NO_STRENGTH_ABLATION) {
     if (ablation.outcomeSlow || ablation.decay)
         return 0;
     return Math.max(0, (entry.outcome_negative ?? 0) - (entry.outcome_positive ?? 0));
 }
-/** Strength at `now` = decay * retrieval boost * emotional multiplier, clamped to [0, 1]; the basis modes are on DecayOptions.
+/**
+ * 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() is the real clock unless HIPPO_FAKE_NOW is set (eval-only); an explicit `now` wins.
@@ -91,7 +106,8 @@ now = evalNow(), options = {}) {
     const wrongPenalty = Math.pow(DECAY_BASE, Math.min(netWrong(entry, ablation), MAX_WRONG_HALVINGS));
     if (entry.pinned)
         return wrongPenalty;
-    // EVAL-ONLY ablation (see ablation.ts): anchor decay at creation so clock resets from earlier unflagged runs cannot leak in.
+    // EVAL-ONLY ablation (see ablation.ts): anchor decay at creation so clock resets from earlier unflagged runs cannot
+    // leak in.
     const lastRetrieved = new Date(ablation.recallBoost ? entry.created : entry.last_retrieved);
     const daysSince = (now.getTime() - lastRetrieved.getTime()) / DAY_MS;
     const rewardFactor = calculateRewardFactor(entry, ablation);
@@ -113,7 +129,8 @@ function decayExponentFor(options, daysSince, halfLifeDays) {
     let effectiveHalfLife = halfLifeDays;
     const basis = options.decayBasis ?? 'clock';
     if (basis === 'session') {
-        // Each sleep cycle counts as one "day"; sessions since last retrieval are estimated from wall time and the average 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;
@@ -134,7 +151,8 @@ function retrievalBoostFor(entry, ablation) {
         ? 1.0
         : 1 + RETRIEVAL_BOOST_SLOPE * Math.log2(entry.retrieval_count + 1);
 }
-const HIGH_SCHEMA_FIT = 0.7;
+/** A memory counts as high schema fit strictly above this. */
+export const HIGH_SCHEMA_FIT = 0.7;
 const HIGH_FIT_HALF_LIFE_FACTOR = 1.5;
 const LOW_SCHEMA_FIT = 0.3;
 const LOW_FIT_HALF_LIFE_FACTOR = 0.5;
@@ -161,7 +179,10 @@ export function deriveHalfLife(base, entry) {
     }
     return hl;
 }
-/** Counts the outcome; calculateStrength turns the counts into a reward factor on the half-life, so there is no fixed delta here. */
+/**
+ * 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,
@@ -205,18 +226,30 @@ export function confidenceLabel(entry, now = evalNow()) {
         warn: agedOut || tier === 'stale' || tier === 'inferred',
     };
 }
-/** The stored confidence, or 'stale' once the entry is aged out (not retrieved for AGED_OUT_AFTER_DAYS; pinned and verified exempt). */
+/**
+ * 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 in days before deriveHalfLife's multipliers: 365 because 7 lost the current fact far more often and 730 did no better.
+/**
+ * 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;
+/** The flat half-life the decision, incident and other object writers gave their memories before they took the
+ * default. */
+export const LEGACY_TYPED_HALF_LIFE = 90;
 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) }));
+export const KEEP_PAIRS = AGENT_MEMORY_TOOLS.map((t) => ({
+    tag: t.tag,
+    sourcePrefix: toolSourcePrefix(t.id),
+}));
 export function isKeptForGood(entry) {
-    return !entry.superseded_by && KEEP_PAIRS.some((p) => entry.tags.includes(p.tag) && entry.source.startsWith(p.sourcePrefix));
+    return (!entry.superseded_by &&
+        KEEP_PAIRS.some((p) => entry.tags.includes(p.tag) && entry.source.startsWith(p.sourcePrefix)));
 }
 export function canAutoDelete(entry) {
     return !entry.pinned && entry.kind !== 'raw' && !isKeptForGood(entry);
@@ -226,8 +259,8 @@ export function createMemory(content, options = {}) {
     const now = evalNow().toISOString(); // honors HIPPO_FAKE_NOW (eval-only)
     const layer = options.layer ?? Layer.Episodic;
     const tags = options.tags ?? [];
-    const emotional_valence = options.emotional_valence ?? inferValence(tags);
-    const schema_fit = options.schema_fit ?? DEFAULT_SCHEMA_FIT;
+    const emotional_valence = options.emotionalValence ?? inferValence(tags);
+    const schema_fit = options.schemaFit ?? DEFAULT_SCHEMA_FIT;
     const half_life_days = deriveHalfLife(options.baseHalfLifeDays ?? DEFAULT_HALF_LIFE_DAYS, { tags, schema_fit });
     const entry = {
         id: generateId(layer === Layer.Semantic ? 'sem' : 'mem'),
@@ -250,18 +283,18 @@ export function createMemory(content, options = {}) {
         content,
         parents: [],
         starred: false,
-        trace_outcome: options.trace_outcome ?? null,
-        source_session_id: options.source_session_id ?? null,
-        valid_from: options.valid_from ?? now,
+        trace_outcome: options.traceOutcome ?? null,
+        source_session_id: options.sourceSessionId ?? null,
+        valid_from: options.validFrom ?? now,
         superseded_by: null,
-        extracted_from: options.extracted_from ?? null,
-        dag_level: options.dag_level ?? 0,
-        dag_parent_id: options.dag_parent_id ?? null,
+        extracted_from: options.extractedFrom ?? null,
+        dag_level: options.dagLevel ?? 0,
+        dag_parent_id: options.dagParentId ?? null,
         kind: options.kind ?? 'distilled',
         scope: options.scope ?? null,
         owner: options.owner ?? null,
-        artifact_ref: options.artifact_ref ?? null,
-        tenantId: options.tenantId ?? DEFAULT_TENANT_ID,
+        artifact_ref: options.artifactRef ?? null,
+        tenant_id: options.tenantId ?? DEFAULT_TENANT_ID,
     };
     entry.strength = calculateStrength(entry);
     return entry;
@@ -272,11 +305,14 @@ function assertValidMemoryInput(content, options) {
         throw new BadRequestError(`Memory content too short (${trimmed.length} chars, minimum 3): "${trimmed}"`);
     }
     const validOutcomes = ['success', 'failure', 'partial', null];
-    if (options.trace_outcome !== undefined && !validOutcomes.includes(options.trace_outcome)) {
-        throw new BadRequestError(`Invalid trace_outcome: ${options.trace_outcome}. Must be 'success', 'failure', 'partial', or null.`);
+    if (options.traceOutcome !== undefined && !validOutcomes.includes(options.traceOutcome)) {
+        throw new BadRequestError(`Invalid trace_outcome: ${options.traceOutcome}. Must be 'success', 'failure', 'partial', or null.`);
     }
 }
-/** The row that replaces `old`: a supersede never changes where a memory belongs, so source, scope, session and a stamped origin carry over. */
+/**
+ * The row that replaces `old`: a supersede never changes where a memory belongs, so source, scope, session and a
+ * stamped origin carry over.
+ */
 export function createSuccessor(old, content, opts) {
     const next = createMemory(content, {
         layer: opts.layer ?? old.layer,
@@ -286,7 +322,7 @@ export function createSuccessor(old, content, opts) {
         confidence: 'verified',
         tenantId: opts.tenantId,
         scope: old.scope,
-        source_session_id: old.source_session_id,
+        sourceSessionId: old.source_session_id,
         baseHalfLifeDays: opts.baseHalfLifeDays,
     });
     // A legacy null origin has nothing to carry, so the store stamps it from its own location.
@@ -295,7 +331,9 @@ export function createSuccessor(old, content, opts) {
     }
     return next;
 }
-/** How well new content fits existing knowledge, 0..1: above 0.7 consolidates faster, below 0.3 is novel and decays faster if unused.
+/**
+ * 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) {
     return schemaFitFrom(content, tags, schemaFitSourceOf(existingEntries));
@@ -310,8 +348,18 @@ export function schemaFitSourceOf(entries) {
     }
     return { rows: entries.length, tagCounts, contents: entries.map((e) => e.content) };
 }
+// Tokens of this length or shorter are filler for schema fit.
+const FILLER_TOKEN_MAX_LENGTH = 3;
+// Matching half the tags at average weight scores about 0.5, so the raw overlap ratio is doubled.
+const TAG_OVERLAP_SCALE = 2;
+// Floor on the matches that saturate the content score, so a tiny store cannot saturate it on one hit.
+const CONTENT_ENOUGH_MIN_MATCHES = 5;
 function significantTokens(text) {
-    return new Set(text.toLowerCase().replace(/[^\w\s]/g, ' ').split(/\s+/).filter((t) => t.length > 3));
+    return new Set(text
+        .toLowerCase()
+        .replace(/[^\w\s]/g, ' ')
+        .split(/\s+/)
+        .filter((t) => t.length > FILLER_TOKEN_MAX_LENGTH));
 }
 /** computeSchemaFit against `source`, for a caller that holds counts and texts but no rows. */
 export function schemaFitFrom(content, tags, source) {
@@ -331,13 +379,12 @@ export function schemaFitFrom(content, tags, source) {
             weightedOverlap += Math.log(N / freq) + 1;
         totalWeight += maxIdf;
     }
-    // Scaled so that matching half the tags at average weight gives about 0.5.
-    const tagScore = totalWeight > 0 ? Math.min(1, (weightedOverlap / totalWeight) * 2) : 0;
+    const tagScore = totalWeight > 0 ? Math.min(1, (weightedOverlap / totalWeight) * TAG_OVERLAP_SCALE) : 0;
     const newTokens = significantTokens(content);
     if (newTokens.size === 0)
         return Math.min(1, Math.max(0, tagScore));
     // The content score is capped at 1, which this many matching memories reach.
-    const enough = Math.max(5, N * CONTENT_ENOUGH_FRACTION);
+    const enough = Math.max(CONTENT_ENOUGH_MIN_MATCHES, N * CONTENT_ENOUGH_FRACTION);
     let contentMatches = 0;
     for (const text of source.contents) {
         const entryTokens = significantTokens(text);
@@ -363,7 +410,9 @@ function inferValence(tags) {
     return 'neutral';
 }
 /** 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. */
+ * 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(), options = {}) {
     const ablation = options.ablation ?? NO_STRENGTH_ABLATION;
     if (ablation.recallBoost)

package/dist/core/merged-row.d.ts

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

package/dist/core/merged-row.js

@@ -1,9 +1,13 @@
-// A sleep-merged row copies its sources' texts, so retiring a text (reject, or superseding its source) must reach the row too.
+// A sleep-merged row copies its sources' texts, so retiring a text (reject, or superseding its source) must reach the
+// row too.
 // SHORTCUT: reject rewrites merged rows at once, live and dormant; supersede and `resolve
 // --reject-loser` wait for the next sleep's check, which sees a dormant row only once restored.
 import { generateId } from './memory.js';
 import { duplicateKey, heldTexts, mergedText } from '../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. */
+/**
+ * The row that replaces a merged row once its retired texts leave: undefined when it holds none, null when nothing else
+ * is left.
+ */
 export function mergedSuccessor(row, retired, retiredIds) {
     const texts = heldTexts(row);
     const kept = texts.filter((t) => !retired(t));
@@ -22,7 +26,10 @@ export function mergedSuccessor(row, retired, retiredIds) {
         conflicts_with: [],
     };
 }
-/** Sleep's check on a merged row: drops texts whose source was superseded since the merge, or that a rejection now covers. */
+/**
+ * Sleep's check on a merged row: drops texts whose source was superseded since the merge, or that a rejection now
+ * covers.
+ */
 export function successorAfterRetirement(row, byId, rejected) {
     if (row.source !== 'consolidation' || row.superseded_by)
         return undefined;

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

@@ -1,3 +1,5 @@
-/** The package folder: it holds package.json, bin/ and dist-ui/. The same two steps up from src/core and from dist/core. */
+/**
+ * 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

@@ -1,5 +1,7 @@
 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. */
+/**
+ * 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/particle-refresh.d.ts

@@ -0,0 +1,8 @@
+import { type MemoryEntry } from './memory.js';
+import { type PhysicsParticle } from './physics.js';
+/**
+ * Refresh mass, charge and temperature for existing particles
+ * from current memory attributes (called during consolidation).
+ */
+export declare function refreshParticleProperties(particles: PhysicsParticle[], entries: Map<string, MemoryEntry>, now?: Date): void;
+//# sourceMappingURL=particle-refresh.d.ts.map

package/dist/core/particle-refresh.js

@@ -0,0 +1,22 @@
+// Particle properties follow the memory they stand for; pure, so sleep refreshes them without reaching the store.
+import { evalNow, strengthAblation } from './ablation.js';
+import { calculateStrength } from './memory.js';
+import { computeCharge, computeMass, computeTemperature } from './physics.js';
+import { DAY_MS } from '../util/time.js';
+/**
+ * Refresh mass, charge and temperature for existing particles
+ * from current memory attributes (called during consolidation).
+ */
+export function refreshParticleProperties(particles, entries, now = evalNow()) {
+    for (const p of particles) {
+        const entry = entries.get(p.memoryId);
+        if (!entry)
+            continue;
+        const strength = calculateStrength(entry, now, { ablation: strengthAblation() });
+        const ageDays = (now.getTime() - new Date(entry.created).getTime()) / DAY_MS;
+        p.mass = computeMass(strength, entry.retrieval_count);
+        p.charge = computeCharge(entry.emotional_valence);
+        p.temperature = computeTemperature(ageDays, 1.0);
+    }
+}
+//# sourceMappingURL=particle-refresh.js.map

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

@@ -1,4 +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 interface PhysicsConfig {
     /** Use physics scoring when embeddings available. 'auto' = yes if embeddings exist. */
     enabled: boolean | 'auto';

package/dist/core/physics-config.js

@@ -1,6 +1,10 @@
-/** 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
+    // 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,

package/dist/core/physics.d.ts

@@ -1,7 +1,10 @@
-/** 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,
+/**
+ * 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 EmotionalValence, type MemoryEntry } from './memory.js';
 import type { PhysicsConfig } from './physics-config.js';
 export interface PhysicsParticle {
     memoryId: string;
@@ -43,16 +46,29 @@ 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 move the particle): scalar ranking magnitude F = G_Q * mass * max(0, cosine(pos, 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 in [0, 1]: how aligned the particle's velocity is with the query direction. */
 export declare function velocityAlignmentBonus(particle: PhysicsParticle, queryEmbedding: number[]): number;
-/** 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. */
+/**
+ * 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. */
+/**
+ * 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 (consolidation-time): -drag * velocity / max(1, effectiveHalfLife), with effectiveHalfLife 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 */
@@ -64,11 +80,23 @@ export interface ForceContext {
 /** 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;
-/** Scores all particles against a query embedding; virtual force computation, so it does NOT modify particle positions. */
+/**
+ * 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 content, from a caller with entries in scope); without it ties fall to memoryId,
+/**
+ * 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[];
-/** Nudges a particle toward (good outcome) or away from (bad outcome) the query embedding; new memories respond more (temperature). Mutates 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;
+/**
+ * Initialize physics state for a memory from its embedding vector; returns the new particle without persisting (the
+ * caller must save).
+ */
+export declare function initializeParticle(entry: MemoryEntry, embedding: number[], now?: Date): PhysicsParticle;
 //# sourceMappingURL=physics.d.ts.map

package/dist/core/physics.js

@@ -1,10 +1,20 @@
-/** 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,
+/**
+ * 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 { cosineOf } from './cosine.js';
-import { isRecallBoostAblated } from './ablation.js';
-import { FALLBACK_HALF_LIFE_DAYS } from './memory.js';
+import { evalNow, isRecallBoostAblated, strengthAblation } from './ablation.js';
+import { calculateStrength, FALLBACK_HALF_LIFE_DAYS } from './memory.js';
+import { DAY_MS } from '../util/time.js';
 import { comparePhysicsResultsBy } from './compare.js';
+// Floors that stop a near-zero mass or a coincident pair from dividing a force by about zero.
+const MIN_MASS = 0.01;
+const MIN_COSINE_DISTANCE = 0.01;
+// Mass gained per doubling of the retrieval count.
+const RETRIEVAL_MASS_GAIN = 0.1;
+const NEAR_ZERO = 1e-10;
 export function vecDot(a, b) {
     let sum = 0;
     for (let i = 0; i < a.length; i++)
@@ -38,7 +48,7 @@ export function vecZero(dim) {
 /** Normalize to unit length. Returns zero vector if magnitude < epsilon. */
 export function vecNormalize(v) {
     const mag = vecNorm(v);
-    if (mag < 1e-10)
+    if (mag < NEAR_ZERO)
         return vecZero(v.length);
     return vecScale(v, 1 / mag);
 }
@@ -56,10 +66,12 @@ const CHARGE_MAP = {
     critical: -1.0,
 };
 export function computeMass(strength, retrievalCount) {
-    // EVAL-ONLY ablation (ablation.ts): under the recall-boost flag mass ignores retrieval history, which would otherwise leak strengthening into the ablated
-    // arm's physics-pool rankings (query gravity ranks by mass). Covers both init and refresh callers in physics-state.ts.
+    // EVAL-ONLY ablation (ablation.ts): under the recall-boost flag mass ignores retrieval history, which would otherwise
+    // leak strengthening into the ablated
+    // arm's physics-pool rankings (query gravity ranks by mass). Covers both init and refresh callers in
+    // physics-state.ts.
     const effectiveCount = isRecallBoostAblated() ? 0 : retrievalCount;
-    return Math.max(0.01, strength * (1 + 0.1 * Math.log2(effectiveCount + 1)));
+    return Math.max(MIN_MASS, strength * (1 + RETRIEVAL_MASS_GAIN * Math.log2(effectiveCount + 1)));
 }
 export function computeCharge(valence) {
     return CHARGE_MAP[valence] ?? 0;
@@ -67,7 +79,10 @@ export function computeCharge(valence) {
 export function computeTemperature(ageDays, temperatureDecay) {
     return 1 / (ageDays * temperatureDecay + 1);
 }
-/** Query gravity (retrieval-time, virtual: does not move the particle): scalar ranking magnitude F = G_Q * mass * max(0, cosine(pos, 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 function queryGravityMagnitude(particle, queryEmbedding, G_query) {
     const cos = cosineOf(particle.position, queryEmbedding);
     return G_query * particle.mass * Math.pow(Math.max(0, cos), 2);
@@ -78,13 +93,17 @@ export function velocityAlignmentBonus(particle, queryEmbedding) {
         return 0;
     const velMag = vecNorm(particle.velocity);
     const qNorm = vecNorm(queryEmbedding);
-    if (velMag < 1e-10 || qNorm < 1e-10)
+    if (velMag < NEAR_ZERO || qNorm < NEAR_ZERO)
         return 0;
     const alignment = vecDot(particle.velocity, queryEmbedding) / (velMag * qNorm);
     return Math.max(0, alignment);
 }
-/** 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. */
+/**
+ * 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 function attractionForce(pi, pj, G_memory, out = vecZero(pi.position.length), diff = vecZero(pi.position.length)) {
     const cos = cosineOf(pi.position, pj.position);
     if (cos <= 0)
@@ -94,23 +113,29 @@ export function attractionForce(pi, pj, G_memory, out = vecZero(pi.position.leng
     for (let k = 0; k < out.length; k++)
         diff[k] = pj.position[k] - pi.position[k];
     const norm = vecNorm(diff);
-    if (norm < 1e-10)
+    if (norm < NEAR_ZERO)
         return out;
     const inv = 1 / norm;
     for (let k = 0; k < out.length; k++)
         out[k] += diff[k] * inv * magnitude;
     return out;
 }
-/** 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. */
+/**
+ * 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 function repulsionForce(pi, pj, K_repulsion) {
     const cos = cosineOf(pi.position, pj.position);
-    const dist = Math.max(0.01, 1 - cos);
+    const dist = Math.max(MIN_COSINE_DISTANCE, 1 - cos);
     const magnitude = K_repulsion * pi.mass * pj.mass / (dist * dist);
     // Direction: away from j
     const direction = vecNormalize(vecSub(pi.position, pj.position));
     return vecScale(direction, magnitude);
 }
-/** Drag force (consolidation-time): -drag * velocity / max(1, effectiveHalfLife), with effectiveHalfLife 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 function dragForce(particle, drag, effectiveHalfLife) {
     const damping = drag / Math.max(1, effectiveHalfLife);
     return vecScale(particle.velocity, -damping);
@@ -142,7 +167,7 @@ function computeNetForce(i, particles, ctx, diff) {
 /** Acceleration of particle i: its net force divided by mass, scaled in place. */
 function computeAcceleration(i, particles, ctx, diff) {
     const accel = computeNetForce(i, particles, ctx, diff);
-    const inv = 1 / Math.max(0.01, particles[i].mass);
+    const inv = 1 / Math.max(MIN_MASS, particles[i].mass);
     for (let k = 0; k < accel.length; k++)
         accel[k] *= inv;
     return accel;
@@ -233,9 +258,13 @@ export function computeSystemEnergy(particles, G_memory) {
     }
     return { kinetic, potential, total: kinetic + potential };
 }
-/** Scores all particles against a query embedding; virtual force computation, so it does NOT modify particle positions. */
+/**
+ * Scores all particles against a query embedding; virtual force computation, so it does NOT modify particle positions.
+ */
 export function physicsScore(particles, queryEmbedding, config, 
-/** Cross-ingest-stable tie key per memoryId (typically the memory content, from a caller with entries in scope); without it ties fall to memoryId,
+/**
+ * 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) {
     if (particles.length === 0 || queryEmbedding.length === 0)
@@ -251,7 +280,8 @@ tieKeyOf) {
             finalScore: gravity + momentum,
         };
     });
-    // Base-score order picks the cluster_top_k amplification SET (which mutates scores), so ties must be cross-ingest-stable
+    // Base-score order picks the cluster_top_k amplification SET (which mutates scores), so ties must be
+    // cross-ingest-stable
     // when the caller supplies a content tie key (see comparePhysicsResultsBy in compare.ts).
     const tie = tieKeyOf ? (r) => tieKeyOf(r.memoryId) : undefined;
     results.sort(comparePhysicsResultsBy((r) => r.baseScore, tie));
@@ -292,7 +322,10 @@ function applyClusterAmplification(results, particles, config) {
         top[i].finalScore = top[i].baseScore * amplification;
     }
 }
-/** Nudges a particle toward (good outcome) or away from (bad outcome) the query embedding; new memories respond more (temperature). Mutates 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 function applyOutcomeFeedback(particle, queryEmbedding, good, feedbackAlpha) {
     if (particle.position.length === 0 || particle.position.length !== queryEmbedding.length)
         return;
@@ -301,4 +334,21 @@ export function applyOutcomeFeedback(particle, queryEmbedding, good, feedbackAlp
     const nudge = vecScale(direction, sign * feedbackAlpha * particle.temperature);
     particle.position = vecNormalize(vecAdd(particle.position, nudge));
 }
+/**
+ * Initialize physics state for a memory from its embedding vector; returns the new particle without persisting (the
+ * caller must save).
+ */
+export function initializeParticle(entry, embedding, now = evalNow()) {
+    const strength = calculateStrength(entry, now, { ablation: strengthAblation() });
+    const ageDays = (now.getTime() - new Date(entry.created).getTime()) / DAY_MS;
+    return {
+        memoryId: entry.id,
+        position: [...embedding], // copy: position will diverge from original embedding
+        velocity: vecZero(embedding.length),
+        mass: computeMass(strength, entry.retrieval_count),
+        charge: computeCharge(entry.emotional_valence),
+        temperature: computeTemperature(ageDays, 1.0),
+        lastSimulation: now.toISOString(),
+    };
+}
 //# sourceMappingURL=physics.js.map