hippo-memory 2.0.0 → 2.1.0

package/dist/core/memory.d.ts

@@ -44,7 +44,10 @@ export interface MemoryEntry {
     descendant_count?: number;
     earliest_at?: string | null;
     latest_at?: string | null;
-    /** True when a child was invalidated, superseded, forgotten or archived since the last rebuild; sleep clears it. Always false below level 2. */
+    /**
+     * True when a child was invalidated, superseded, forgotten or archived since the last rebuild; sleep clears it.
+     * Always false below level 2.
+     */
     summary_dirty?: boolean;
     /** ISO 8601 time of the last successful rebuild, or null if never rebuilt. */
     last_rebuilt_at?: string | null;
@@ -57,13 +60,23 @@ export interface MemoryEntry {
     owner: string | null;
     artifact_ref: string | null;
     tenant_id: string;
-    /** Owning project, lowercased; '' = user-global (injectable everywhere), null = none known (legacy or unnamed write), denied by ambient context.
+    /**
+     * Owning project, lowercased; '' = user-global (injectable everywhere), null = none known (legacy or unnamed write),
+     * denied by ambient context.
      *  Stamped at write time by stampOriginProject (src/store/entry-row.ts); undefined only before the first write. */
     origin_project?: string | null;
-    /** Raw FTS5 bm25() from the search path (negative, lower = better); set only for a non-empty query the FTS join answered.
+    /**
+     * Raw FTS5 bm25() from the search path (negative, lower = better); set only for a non-empty query the FTS join
+     * answered.
      *  Not comparable to the JS scorer in src/search/bm25.ts, so read it as rank metadata only. */
     bm25_score?: number;
 }
+/** Named dag_level values; level 0 is a raw leaf. */
+export declare const DAG_LEVEL: {
+    readonly extracted: 1;
+    readonly topic: 2;
+    readonly entity: 3;
+};
 /** Tag on a memory whose named file/symbol/script changed after it was stored. */
 export declare const CHURN_STALE_TAG = "churn-stale";
 export declare const EMOTIONAL_MULTIPLIERS: {
@@ -72,22 +85,36 @@ export declare const EMOTIONAL_MULTIPLIERS: {
     negative: number;
     critical: number;
 };
-/** 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 declare function _resetLossAversionRatioCacheForTests(): void;
-/** 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 declare function applyLossAversionRatio(valence: EmotionalValence, baseMultiplier: number): number;
-/** 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 declare function calculateRewardFactor(entry: Pick<MemoryEntry, 'outcome_positive' | 'outcome_negative'>, ablation?: StrengthAblation): number;
 /** Bad marks alone never push a memory under sleep's 0.05 retire line; supersede is the hard correction. */
 export declare const MAX_WRONG_HALVINGS = 3;
 export declare const DECAY_BASE = 0.5;
 export declare const REWARD_SLOPE = 0.5;
 export declare 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 declare function netWrong(entry: Pick<MemoryEntry, 'outcome_positive' | 'outcome_negative'>, ablation?: StrengthAblation): number;
 /** What calculateStrength reads, so a caller can score a row without loading its text. */
 export type StrengthInputs = Pick<MemoryEntry, 'pinned' | 'created' | 'last_retrieved' | 'half_life_days' | 'retrieval_count' | 'emotional_valence' | 'outcome_positive' | 'outcome_negative'>;
-/** Decay basis: clock = wall time, session = per sleep cycle (intermittent agents), adaptive = half-life scaled by session frequency. */
+/**
+ * Decay basis: clock = wall time, session = per sleep cycle (intermittent agents), adaptive = half-life scaled by
+ * session frequency.
+ */
 export interface DecayOptions {
     decayBasis?: 'clock' | 'session' | 'adaptive';
     /** Average interval between sleep cycles, in days. Used by 'adaptive' and 'session' modes. */
@@ -97,12 +124,19 @@ export interface DecayOptions {
     /** EVAL-ONLY switches resolved once at the entry layer (`strengthAblation()`); absent means production scoring. */
     ablation?: StrengthAblation;
 }
-/** 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 declare function calculateStrength(entry: StrengthInputs, now?: Date, options?: DecayOptions): number;
+/** A memory counts as high schema fit strictly above this. */
+export declare const HIGH_SCHEMA_FIT = 0.7;
 /** The base half-life scaled by the PLAN.md signals: an error tag, and high or low schema fit. */
 export declare function deriveHalfLife(base: number, entry: Partial<MemoryEntry>): number;
-/** 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 declare function applyOutcome(entry: MemoryEntry, good: boolean): MemoryEntry;
 /** applyOutcome as a served outcome applies it: a good outcome reconfirms the entry, so its churn-stale tag goes. */
 export declare function entryAfterOutcome(entry: MemoryEntry, good: boolean): MemoryEntry;
@@ -120,14 +154,24 @@ export declare function confidenceLabel(entry: MemoryEntry, now?: Date): {
     text: string;
     warn: boolean;
 };
-/** 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 declare function resolveConfidence(entry: MemoryEntry, now?: Date): ConfidenceLevel;
-/** 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 declare 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 declare const LEGACY_TYPED_HALF_LIFE = 90;
 export declare const COMPACTION_MEMORY_TAG = "compaction-memory";
 export declare const COMPACTION_SOURCE_PREFIX = "compaction:";
-/** An imported agent memory is kept for good: the agent's note file is its record. It needs both its tool's tag and a source with that tool's prefix,
+/**
+ * An imported agent memory is kept for good: the agent's note file is its record. It needs both its tool's tag and a
+ * source with that tool's prefix,
  *  since merge copies source tags onto rows whose source is 'consolidation'. */
 export interface KeepPair {
     readonly tag: string;
@@ -136,31 +180,40 @@ export interface KeepPair {
 export declare const KEEP_PAIRS: readonly KeepPair[];
 export declare function isKeptForGood(entry: Pick<MemoryEntry, 'tags' | 'source' | 'superseded_by'>): boolean;
 export declare function canAutoDelete(entry: Pick<MemoryEntry, 'pinned' | 'kind' | 'tags' | 'source' | 'superseded_by'>): boolean;
+/** Options are camelCase; `MemoryEntry` keeps the snake_case stored-row names. */
 export interface CreateMemoryOptions {
     layer?: Layer;
     tags?: string[];
-    emotional_valence?: EmotionalValence;
+    emotionalValence?: EmotionalValence;
     pinned?: boolean;
-    schema_fit?: number;
+    schemaFit?: number;
     source?: string;
     confidence?: ConfidenceLevel;
-    /** The store's `loadConfig(hippoRoot).defaultHalfLifeDays`; required so no writer silently gets the compiled default. */
+    /**
+     * The store's `loadConfig(hippoRoot).defaultHalfLifeDays`; required so no writer silently gets the compiled default.
+     */
     baseHalfLifeDays: number;
-    trace_outcome?: TraceOutcome;
-    source_session_id?: string | null;
-    valid_from?: string;
-    extracted_from?: string;
-    dag_level?: number;
-    dag_parent_id?: string;
+    traceOutcome?: TraceOutcome;
+    sourceSessionId?: string | null;
+    validFrom?: string;
+    extractedFrom?: string;
+    dagLevel?: number;
+    dagParentId?: string;
     kind?: MemoryKind;
     scope?: string | null;
     owner?: string | null;
-    artifact_ref?: string | null;
+    artifactRef?: string | null;
     tenantId?: string;
 }
-/** Create a new memory entry with defaults. Untyped JavaScript callers that omit the options get the compiled default half-life. */
+/**
+ * Create a new memory entry with defaults. Untyped JavaScript callers that omit the options get the compiled default
+ * half-life.
+ */
 export declare function createMemory(content: string, options: CreateMemoryOptions): MemoryEntry;
-/** 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 declare function createSuccessor(old: MemoryEntry, content: string, opts: {
     tenantId: string;
     baseHalfLifeDays: number;
@@ -168,7 +221,9 @@ export declare function createSuccessor(old: MemoryEntry, content: string, opts:
     tags?: string[];
     pinned?: boolean;
 }): MemoryEntry;
-/** 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 declare function computeSchemaFit(content: string, tags: string[], existingEntries: MemoryEntry[]): number;
 /** What schema fit reads from `entries`, built once for a caller that scores many contents against the same rows. */
@@ -184,6 +239,8 @@ export interface SchemaFitSource {
 /** computeSchemaFit against `source`, for a caller that holds counts and texts but no rows. */
 export declare function schemaFitFrom(content: string, tags: readonly string[], source: SchemaFitSource): number;
 /** 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 declare function markRetrieved(entries: MemoryEntry[], now?: Date, options?: Pick<DecayOptions, 'ablation'>): MemoryEntry[];
 //# sourceMappingURL=memory.d.ts.map

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,17 +283,17 @@ 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,
+        artifact_ref: options.artifactRef ?? null,
         tenant_id: options.tenantId ?? DEFAULT_TENANT_ID,
     };
     entry.strength = calculateStrength(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));
@@ -317,7 +355,11 @@ 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 > FILLER_TOKEN_MAX_LENGTH));
+    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) {
@@ -368,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,5 +1,8 @@
-/** 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, type MemoryEntry } from './memory.js';
 import type { PhysicsConfig } from './physics-config.js';
@@ -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,13 +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). */
+/**
+ * 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