hippo-memory 1.69.0 → 1.71.0

package/dist/core/memory.d.ts

@@ -0,0 +1,183 @@
+/** Core data model for Hippo memory entries, based on the strength formula from PLAN.md. */
+export declare const DEFAULT_SCHEMA_FIT = 0.5;
+export declare const FALLBACK_HALF_LIFE_DAYS = 7;
+export declare enum Layer {
+    Buffer = "buffer",
+    Episodic = "episodic",
+    Semantic = "semantic",
+    Trace = "trace"
+}
+export type EmotionalValence = 'neutral' | 'positive' | 'negative' | 'critical';
+export type ConfidenceLevel = 'verified' | 'observed' | 'inferred' | 'stale';
+export type TraceOutcome = 'success' | 'failure' | 'partial' | null;
+export type MemoryKind = 'raw' | 'distilled' | 'superseded' | 'archived';
+export interface MemoryEntry {
+    id: string;
+    created: string;
+    last_retrieved: string;
+    retrieval_count: number;
+    strength: number;
+    half_life_days: number;
+    layer: Layer;
+    tags: string[];
+    emotional_valence: EmotionalValence;
+    schema_fit: number;
+    source: string;
+    outcome_score: number | null;
+    outcome_positive: number;
+    outcome_negative: number;
+    conflicts_with: string[];
+    pinned: boolean;
+    confidence: ConfidenceLevel;
+    content: string;
+    parents: string[];
+    starred: boolean;
+    trace_outcome: TraceOutcome;
+    source_session_id: string | null;
+    valid_from: string;
+    superseded_by: string | null;
+    extracted_from: string | null;
+    dag_level: number;
+    dag_parent_id: string | null;
+    descendant_count?: number;
+    earliest_at?: string | null;
+    latest_at?: string | null;
+    /** 1 when a child was invalidated, superseded, forgotten or archived since the last rebuild; sleep clears it. Always 0 below level 2. */
+    summary_dirty?: 0 | 1;
+    /** ISO 8601 time of the last successful rebuild, or null if never rebuilt. */
+    last_rebuilt_at?: string | null;
+    /** Count of successful rebuilds: 0 at the first buildDag write, bumped by each rebuild. */
+    rebuild_count?: number;
+    /** Reserved: ISO 8601 time the level-3 entity profile was built; only set on dag_level=3 rows. */
+    dag_level_3_built_at?: string | null;
+    kind: MemoryKind;
+    scope: string | null;
+    owner: string | null;
+    artifact_ref: string | null;
+    tenantId: string;
+    /** 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.
+     *  Not comparable to the JS scorer in src/search/bm25.ts, so read it as rank metadata only. */
+    bm25_score?: number;
+}
+/** 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: {
+    neutral: number;
+    positive: number;
+    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). */
+export declare function _resetLossAversionRatioCacheForTests(): void;
+/** 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. */
+export declare function calculateRewardFactor(entry: Pick<MemoryEntry, 'outcome_positive' | 'outcome_negative'>): 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. */
+export declare function netWrong(entry: Pick<MemoryEntry, 'outcome_positive' | 'outcome_negative'>): 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. */
+export interface DecayOptions {
+    decayBasis?: 'clock' | 'session' | 'adaptive';
+    /** Average interval between sleep cycles, in days. Used by 'adaptive' and 'session' modes. */
+    avgSessionIntervalDays?: number;
+    /** Total sleep cycles completed. Used by consolidation tracking. */
+    sleepCount?: number;
+}
+/** 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;
+/** 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. */
+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;
+/** A new id: `prefix_` plus the first ID_SUFFIX_CHARS hex characters of a random UUID. */
+export declare function generateId(prefix?: string): string;
+/** What the confidence facets read, so a caller can derive them from a row it loaded only in part. */
+export type ConfidenceInputs = Pick<MemoryEntry, 'pinned' | 'confidence' | 'last_retrieved'>;
+export interface ConfidenceFacets {
+    tier: ConfidenceLevel;
+    agedOut: boolean;
+}
+export declare function confidenceFacets(entry: MemoryEntry, now?: Date): ConfidenceFacets;
+export declare function facetsOf(entry: ConfidenceInputs, now: Date): ConfidenceFacets;
+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). */
+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.
+ *  `hippo sleep` moves memories still on an older base (src/consolidate/half-life-migration.ts). */
+export declare const DEFAULT_HALF_LIFE_DAYS = 365;
+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,
+ *  since merge copies source tags onto rows whose source is 'consolidation'. */
+export interface KeepPair {
+    readonly tag: string;
+    readonly sourcePrefix: string;
+}
+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;
+export interface CreateMemoryOptions {
+    layer?: Layer;
+    tags?: string[];
+    emotional_valence?: EmotionalValence;
+    pinned?: boolean;
+    schema_fit?: number;
+    source?: string;
+    confidence?: ConfidenceLevel;
+    /** 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;
+    kind?: MemoryKind;
+    scope?: string | null;
+    owner?: string | null;
+    artifact_ref?: string | null;
+    tenantId?: string;
+}
+/** 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. */
+export declare function createSuccessor(old: MemoryEntry, content: string, opts: {
+    tenantId: string;
+    baseHalfLifeDays: number;
+    layer?: Layer;
+    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.
+ *  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 a set of memories, so a store can answer without loading its rows. */
+export interface SchemaFitSource {
+    readonly rows: number;
+    /** How many times each tag appears across the set. */
+    readonly tagCounts: ReadonlyMap<string, number>;
+    /** Each memory's text; the walk stops once more matches cannot move the score. */
+    readonly contents: Iterable<string>;
+}
+/** 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. */
+export declare function markRetrieved(entries: MemoryEntry[], now?: Date): MemoryEntry[];
+//# sourceMappingURL=memory.d.ts.map

package/dist/core/memory.js

@@ -0,0 +1,380 @@
+/** 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;
+export const FALLBACK_HALF_LIFE_DAYS = 7;
+export var Layer;
+(function (Layer) {
+    Layer["Buffer"] = "buffer";
+    Layer["Episodic"] = "episodic";
+    Layer["Semantic"] = "semantic";
+    Layer["Trace"] = "trace";
+})(Layer || (Layer = {}));
+/** 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.
+export const EMOTIONAL_MULTIPLIERS = {
+    neutral: 1.0,
+    positive: 1.0,
+    negative: 2.0, // error-tagged
+    critical: 2.0,
+};
+// 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;
+// Read once: calculateStrength runs per entry inside hot loops (src/api, src/consolidate, src/search).
+let _lossAversionRatioCache;
+function getLossAversionRatio() {
+    if (_lossAversionRatioCache !== undefined)
+        return _lossAversionRatioCache;
+    const raw = envLossAversionRatio();
+    if (raw === undefined || raw === '') {
+        _lossAversionRatioCache = 1.0;
+        return 1.0;
+    }
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed < LOSS_AVERSION_RATIO_MIN) {
+        _lossAversionRatioCache = 1.0;
+        return 1.0;
+    }
+    _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). */
+export function _resetLossAversionRatioCacheForTests() {
+    _lossAversionRatioCache = undefined;
+}
+/** 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. */
+export function calculateRewardFactor(entry) {
+    // EVAL-ONLY ablation (see ablation.ts): the slow outcome channel.
+    if (isOutcomeSlowAblated())
+        return 1.0;
+    const pos = entry.outcome_positive ?? 0;
+    const neg = entry.outcome_negative ?? 0;
+    if (pos === 0 && neg === 0)
+        return 1.0;
+    const ratio = (pos - neg) / (pos + neg + 1);
+    return 1 + REWARD_SLOPE * ratio;
+}
+/** Bad marks alone never push a memory under sleep's 0.05 retire line; supersede is the hard correction. */
+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));
+}
+/** 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.
+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 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;
+    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 := 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);
+    const baseMultiplier = EMOTIONAL_MULTIPLIERS[entry.emotional_valence] ?? 1.0;
+    const emotionalMultiplier = applyLossAversionRatio(entry.emotional_valence, baseMultiplier);
+    const raw = decay * retrievalBoost * emotionalMultiplier;
+    const clamped = Math.min(1.0, Math.max(0.0, raw));
+    return Number.isFinite(clamped) ? clamped * wrongPenalty : 0.0;
+}
+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.
+        const avgInterval = options.avgSessionIntervalDays ?? 1;
+        const sessionsSince = avgInterval > 0 ? Math.max(0, daysSince / avgInterval) : daysSince;
+        return sessionsSince / effectiveHalfLife;
+    }
+    if (basis === 'adaptive') {
+        // Scale half-life by session frequency: infrequent agents get longer half-lives
+        const avgInterval = options.avgSessionIntervalDays ?? 0;
+        if (avgInterval > 1) {
+            effectiveHalfLife *= avgInterval;
+        }
+        return daysSince / effectiveHalfLife;
+    }
+    return daysSince / effectiveHalfLife;
+}
+// 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);
+}
+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;
+// Schema fit blends tag coverage and content similarity; a content match needs this share of shared tokens.
+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;
+    if (entry.tags?.includes('error')) {
+        hl *= ERROR_TAG_HALF_LIFE_FACTOR;
+    }
+    if (entry.schema_fit !== undefined && entry.schema_fit > HIGH_SCHEMA_FIT) {
+        hl *= HIGH_FIT_HALF_LIFE_FACTOR;
+    }
+    if (entry.schema_fit !== undefined && entry.schema_fit < LOW_SCHEMA_FIT) {
+        hl *= LOW_FIT_HALF_LIFE_FACTOR;
+    }
+    return hl;
+}
+/** 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,
+        outcome_score: good ? 1 : -1,
+        outcome_positive: (entry.outcome_positive ?? 0) + (good ? 1 : 0),
+        outcome_negative: (entry.outcome_negative ?? 0) + (good ? 0 : 1),
+    };
+    updated.strength = calculateStrength(updated);
+    return updated;
+}
+/** applyOutcome as a served outcome applies it: a good outcome reconfirms the entry, so its churn-stale tag goes. */
+export function entryAfterOutcome(entry, good) {
+    const updated = applyOutcome(entry, good);
+    if (!good || !updated.tags.includes(CHURN_STALE_TAG))
+        return updated;
+    return { ...updated, tags: updated.tags.filter((t) => t !== CHURN_STALE_TAG) };
+}
+/** 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 > AGED_OUT_AFTER_DAYS;
+}
+export function confidenceFacets(entry, now = evalNow()) {
+    return facetsOf(entry, now);
+}
+export function facetsOf(entry, now) {
+    return { tier: entry.confidence, agedOut: isAgedOut(entry, now) };
+}
+// 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 {
+        text: agedOut ? `${tier}, aged` : tier,
+        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). */
+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.
+ *  `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) }));
+export function isKeptForGood(entry) {
+    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);
+}
+export function createMemory(content, options = {}) {
+    assertValidMemoryInput(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 half_life_days = deriveHalfLife(options.baseHalfLifeDays ?? DEFAULT_HALF_LIFE_DAYS, { tags, schema_fit });
+    const entry = {
+        id: generateId(layer === Layer.Semantic ? 'sem' : 'mem'),
+        created: now,
+        last_retrieved: now,
+        retrieval_count: 0,
+        strength: 1.0,
+        half_life_days,
+        layer,
+        tags,
+        emotional_valence,
+        schema_fit,
+        source: options.source ?? 'cli',
+        outcome_score: null,
+        outcome_positive: 0,
+        outcome_negative: 0,
+        conflicts_with: [],
+        pinned: options.pinned ?? false,
+        confidence: options.confidence ?? 'verified',
+        content,
+        parents: [],
+        starred: false,
+        trace_outcome: options.trace_outcome ?? null,
+        source_session_id: options.source_session_id ?? null,
+        valid_from: options.valid_from ?? now,
+        superseded_by: null,
+        extracted_from: options.extracted_from ?? null,
+        dag_level: options.dag_level ?? 0,
+        dag_parent_id: options.dag_parent_id ?? 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,
+    };
+    entry.strength = calculateStrength(entry);
+    return entry;
+}
+function assertValidMemoryInput(content, options) {
+    const trimmed = content.trim();
+    if (trimmed.length < 3) {
+        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.`);
+    }
+}
+/** 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,
+        tags: opts.tags ?? [...old.tags],
+        pinned: opts.pinned ?? old.pinned,
+        source: old.source,
+        confidence: 'verified',
+        tenantId: opts.tenantId,
+        scope: old.scope,
+        source_session_id: old.source_session_id,
+        baseHalfLifeDays: opts.baseHalfLifeDays,
+    });
+    // A legacy null origin has nothing to carry, so the store stamps it from its own location.
+    if (isJsonString(old.origin_project)) {
+        next.origin_project = old.origin_project;
+    }
+    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.
+ *  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) {
+        for (const tag of entry.tags) {
+            tagCounts.set(tag, (tagCounts.get(tag) ?? 0) + 1);
+        }
+    }
+    return schemaFitFrom(content, tags, { rows: existingEntries.length, tagCounts, contents: existingEntries.map((e) => e.content) });
+}
+function significantTokens(text) {
+    return new Set(text.toLowerCase().replace(/[^\w\s]/g, ' ').split(/\s+/).filter((t) => t.length > 3));
+}
+/** computeSchemaFit against `source`, for a caller that holds counts and texts but no rows. */
+export function schemaFitFrom(content, tags, source) {
+    const N = source.rows;
+    if (N === 0)
+        return DEFAULT_SCHEMA_FIT;
+    const tagFreq = source.tagCounts;
+    if (tags.length === 0 && tagFreq.size === 0)
+        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;
+    const maxIdf = Math.log(N + 1) + 1;
+    for (const tag of tags) {
+        const freq = tagFreq.get(tag) ?? 0;
+        if (freq > 0)
+            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 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);
+    let contentMatches = 0;
+    for (const text of source.contents) {
+        const entryTokens = significantTokens(text);
+        let shared = 0;
+        for (const token of newTokens) {
+            if (entryTokens.has(token))
+                shared++;
+        }
+        if (shared / newTokens.size > CONTENT_TOKEN_SHARE_MIN && ++contentMatches >= enough)
+            break;
+    }
+    const contentScore = Math.min(1, contentMatches / enough);
+    const fit = TAG_FIT_WEIGHT * tagScore + CONTENT_FIT_WEIGHT * contentScore;
+    return Math.min(1, Math.max(0, fit));
+}
+function inferValence(tags) {
+    if (tags.includes('critical'))
+        return 'critical';
+    if (tags.includes('error'))
+        return 'negative';
+    if (tags.includes('success') || tags.includes('win'))
+        return 'positive';
+    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. */
+export function markRetrieved(entries, now = evalNow()) {
+    if (isRecallBoostAblated())
+        return entries;
+    return entries.map((e) => {
+        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(),
+            half_life_days: wrong ? e.half_life_days : e.half_life_days + RETRIEVAL_HALF_LIFE_GAIN_DAYS,
+        };
+        updated.strength = calculateStrength(updated, now);
+        return updated;
+    });
+}
+//# sourceMappingURL=memory.js.map

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/{physics-config.d.ts → 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/{physics-config.js → 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,