hippo-memory 1.69.0 → 1.71.0

package/dist/memory.js

@@ -1,522 +0,0 @@
-/**
- * Core data model for Hippo memory entries.
- * Based on the strength formula from PLAN.md.
- */
-import { envLossAversionRatio } from './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-memories/tools.js';
-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';
-// Emotional multipliers from PLAN.md. Losses weigh ~2x equivalent gains (Lovallo-Kahneman TFAS empirics),
-// so negative is 2.0. `negative` is further scaled per-process by HIPPO_LOSS_AVERSION_RATIO
-// (env var, default 1.0; see getLossAversionRatio + applyLossAversionRatio).
-const EMOTIONAL_MULTIPLIERS = {
-    neutral: 1.0,
-    positive: 1.0,
-    negative: 2.0, // error-tagged
-    critical: 2.0,
-};
-/**
- * Module-level lazy-cached read of HIPPO_LOSS_AVERSION_RATIO.
- *
- * `calculateStrength` is called per-entry inside hot recall loops
- * (api.ts/consolidate.ts/search.ts), so a per-call `process.env` lookup
- * would multiply N entries by M recalls of lookup cost. Lazy module-cache
- * reads the env ONCE on first call and memoizes for the process lifetime.
- * Test isolation via `_resetLossAversionRatioCacheForTests()` below.
- */
-/**
- * Minimum acceptable ratio. Below this, the negative multiplier
- * (2.0 * ratio) becomes small enough that calculateStrength * decay can fall
- * below `DECAY_THRESHOLD = 0.05` in `src/consolidate.ts:146`, which would
- * permanently delete non-pinned error-tagged memories on the next sleep
- * cycle. 0.5 is chosen as the floor because (a) it recovers the pre-calibration
- * effective multiplier (2.0 * 0.5 = 1.0 + the negative premium, i.e. 1.5x
- * the pre-calibration default), and (b) below this the user is asking for LESS
- * loss aversion than has ever shipped — that's outside the supported
- * tuning range.
- */
-const LOSS_AVERSION_RATIO_MIN = 0.5;
-/**
- * Validation policy:
- *   - Valid: finite numbers >= 0.5.
- *   - Invalid (silent fallback to 1.0): empty string, non-numeric,
- *     numbers below 0.5 (including 0 and negatives), NaN, +/-Infinity.
- *     Silent because opt-in env vars should not crash production recall
- *     on a typo.
- *
- * Why the 0.5 floor and not 0:
- *   - Rejecting only `0` leaves the same silent data-loss surface for any ratio
- *     below ~0.025 (and worse for aged memories, where even ratio=0.25
- *     can produce strength < DECAY_THRESHOLD = 0.05 in consolidate.ts).
- *     Floor at the pre-calibration equivalent (0.5) so the env var's tuning
- *     range never crosses into the deletion regime.
- *   - Users wanting LESS loss aversion than the pre-calibration 1.5 multiplier
- *     should reconsider the design intent (the calibration was
- *     toward MORE loss aversion, not less). If a future use case
- *     genuinely needs ratio < 0.5, the right path is a separate
- *     `HIPPO_NEGATIVE_MULTIPLIER` env override.
- */
-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);
-    // Finite + >= 0.5 floor. Anything below 0.5 silently falls back to 1.0
-    // to avoid the consolidation-deletion vector (see JSDoc above).
-    if (!Number.isFinite(parsed) || parsed < LOSS_AVERSION_RATIO_MIN) {
-        _lossAversionRatioCache = 1.0;
-        return 1.0;
-    }
-    _lossAversionRatioCache = parsed;
-    return parsed;
-}
-/**
- * Test-only helper. Tests that mutate `process.env.HIPPO_LOSS_AVERSION_RATIO`
- * MUST call this in BOTH `beforeEach` AND `afterEach`:
- *   - beforeEach: clear any stale cache from a previous test before setting
- *     the env var for this test.
- *   - afterEach: clear the cache so the next test (which may not set the env
- *     var) reads the clean default instead of this test's value.
- * See `tests/emotional-multipliers-j5.test.ts` for the canonical pattern.
- */
-export function _resetLossAversionRatioCacheForTests() {
-    _lossAversionRatioCache = undefined;
-}
-/**
- * Apply the loss-aversion ratio scalar to the `negative` multiplier ONLY.
- * Other valences (positive, critical, neutral) pass through unchanged.
- * `critical` is deliberately NOT scaled, so the calibration only touches the
- * specific empirical claim (TFAS 2x losses-vs-gains).
- */
-function applyLossAversionRatio(valence, baseMultiplier) {
-    if (valence !== 'negative')
-        return baseMultiplier;
-    return baseMultiplier * getLossAversionRatio();
-}
-/**
- * Compute the reward factor from cumulative outcome counts.
- *
- *   reward_ratio  = (positive - negative) / (positive + negative + 1)
- *   reward_factor = 1 + 0.5 * reward_ratio
- *
- * Range: (0.5, 1.5). Neutral (no outcomes) returns 1.0.
- * Modulates effective half-life: memories with consistent positive outcomes
- * decay slower; consistent negative outcomes decay faster.
- */
-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 + 0.5 * ratio;
-}
-/** Bad marks alone never push a memory under sleep's 0.05 retire line; supersede is the hard correction. */
-const MAX_WRONG_HALVINGS = 3;
-/**
- * Net wrongness: bad outcome marks past good ones, never below zero.
- * Strength halves per unit (capped at 3) and recall stops strengthening
- * the memory, so a correction outranks pinning, error tags and heavy recall.
- */
-export function netWrong(entry) {
-    if (isOutcomeSlowAblated() || isDecayAblated())
-        return 0;
-    return Math.max(0, (entry.outcome_negative ?? 0) - (entry.outcome_positive ?? 0));
-}
-/**
- * Calculate current strength at a given time.
- * strength(t) = base_strength * decay * retrieval_boost * emotional_multiplier
- *
- * Decay basis modes:
- * - clock: classic wall-clock decay (daysSince / halfLife)
- * - session: decay by sleep cycles instead of days (sessionsSince / halfLife)
- * - adaptive: wall-clock decay with half-life scaled by session frequency
- *
- * Pinned memories skip time decay; being marked wrong still fades them (netWrong).
- */
-export function calculateStrength(entry, 
-// evalNow(): the real clock unless HIPPO_FAKE_NOW is set (eval-only,
-// simulated-time protocols; see ablation.ts). Explicit `now` always wins.
-now = evalNow(), options = {}) {
-    // Being marked wrong outranks every shield: pinning, error tags, heavy recall.
-    const wrongPenalty = Math.pow(0.5, Math.min(netWrong(entry), MAX_WRONG_HALVINGS));
-    if (entry.pinned)
-        return wrongPenalty;
-    // EVAL-ONLY ablation (see ablation.ts): anchor decay at CREATION, so clock resets persisted by PRIOR
-    // unflagged runs cannot leak strengthening into an ablated arm. Prior-run half_life increments are
-    // NOT reconstructed - see the ablation.ts caveat (fresh stores per arm).
-    const lastRetrieved = new Date(isRecallBoostAblated() ? entry.created : entry.last_retrieved);
-    const daysSince = (now.getTime() - lastRetrieved.getTime()) / (1000 * 60 * 60 * 24);
-    // Reward-proportional half-life modulation
-    const rewardFactor = calculateRewardFactor(entry);
-    let effectiveHalfLife = entry.half_life_days * rewardFactor;
-    // Guard: zero half-life causes 0/0 = NaN in the exponent
-    if (effectiveHalfLife <= 0)
-        return 0.0;
-    const basis = options.decayBasis ?? 'clock';
-    let decayExponent;
-    if (basis === 'session') {
-        // Decay by session count: each sleep cycle = 1 "day" in the decay formula.
-        // Estimate sessions since last retrieval from wall-clock time and avg interval.
-        const avgInterval = options.avgSessionIntervalDays ?? 1;
-        const sessionsSince = avgInterval > 0 ? Math.max(0, daysSince / avgInterval) : daysSince;
-        decayExponent = sessionsSince / effectiveHalfLife;
-    }
-    else 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;
-        }
-        decayExponent = daysSince / effectiveHalfLife;
-    }
-    else {
-        // clock: classic wall-clock decay
-        decayExponent = daysSince / effectiveHalfLife;
-    }
-    // EVAL-ONLY ablation (see ablation.ts): decay term := 1. NOTE the [0,1]
-    // clamp below then caps retrievalBoost at baseline - see ablation.ts
-    // formula note.
-    const decay = isDecayAblated() ? 1.0 : Math.pow(0.5, decayExponent);
-    // Retrieval boost: 1 + 0.1 * log2(retrieval_count + 1). EVAL-ONLY ablation (see ablation.ts) neutralizes
-    // the READ side too, so counts written before the flag cannot leak strengthening into an ablated arm.
-    const retrievalBoost = isRecallBoostAblated() || netWrong(entry) > 0
-        ? 1.0
-        : 1 + 0.1 * Math.log2(entry.retrieval_count + 1);
-    // Emotional multiplier. HIPPO_LOSS_AVERSION_RATIO scales the negative one ONLY; the lazy
-    // module cache makes this one lookup + one multiply, not a per-call process.env read.
-    const baseMultiplier = EMOTIONAL_MULTIPLIERS[entry.emotional_valence] ?? 1.0;
-    const emotionalMultiplier = applyLossAversionRatio(entry.emotional_valence, baseMultiplier);
-    const raw = decay * retrievalBoost * emotionalMultiplier;
-    // Clamp to [0, 1] with NaN guard
-    const clamped = Math.min(1.0, Math.max(0.0, raw));
-    return Number.isFinite(clamped) ? clamped * wrongPenalty : 0.0;
-}
-/** calculateStrength's clock-basis formula as SQL over `memories` columns, flags and multipliers baked in; keep in step.
- *  An unparseable date scores NULL here and 0 in JS, so sums agree. */
-export function strengthSql(now) {
-    const num = (n) => (Number.isInteger(n) ? n.toFixed(1) : String(n));
-    const pos = 'COALESCE(outcome_positive, 0)';
-    const neg = 'COALESCE(outcome_negative, 0)';
-    const wrong = isOutcomeSlowAblated() || isDecayAblated() ? '0' : `MAX(0, ${neg} - ${pos})`;
-    const reward = isOutcomeSlowAblated()
-        ? '1.0'
-        : `(CASE WHEN ${pos} = 0 AND ${neg} = 0 THEN 1.0 ELSE 1.0 + 0.5 * (${pos} - ${neg}) / (${pos} + ${neg} + 1.0) END)`;
-    const halfLife = `(COALESCE(half_life_days, 7) * ${reward})`;
-    const anchor = isRecallBoostAblated() ? 'created' : 'last_retrieved';
-    const nowJulian = num(now.getTime() / 86400000 + 2440587.5);
-    const decay = isDecayAblated() ? '1.0' : `pow(0.5, (${nowJulian} - julianday(${anchor})) / ${halfLife})`;
-    const boost = isRecallBoostAblated()
-        ? '1.0'
-        : `(CASE WHEN ${wrong} > 0 THEN 1.0 ELSE 1.0 + 0.1 * log2(COALESCE(retrieval_count, 0) + 1) END)`;
-    const valences = /* SAFETY: a Record keyed by EmotionalValence */ Object.keys(EMOTIONAL_MULTIPLIERS);
-    const emotion = `(CASE COALESCE(emotional_valence, 'neutral') ${valences
-        .map((v) => `WHEN '${v}' THEN ${num(applyLossAversionRatio(v, EMOTIONAL_MULTIPLIERS[v]))}`)
-        .join(' ')} ELSE 1.0 END)`;
-    const penalty = `pow(0.5, MIN(${wrong}, ${MAX_WRONG_HALVINGS}))`;
-    return `(CASE WHEN pinned THEN ${penalty} WHEN ${halfLife} <= 0 THEN 0.0
-    ELSE MIN(1.0, MAX(0.0, ${decay} * ${boost} * ${emotion})) * ${penalty} END)`;
-}
-/**
- * Derive half-life based on signals, as per PLAN.md table.
- */
-export function deriveHalfLife(base, entry) {
-    let hl = base;
-    // Error-tagged: 2x half-life
-    if (entry.tags?.includes('error')) {
-        hl *= 2;
-    }
-    // High schema fit: consolidates faster (1.5x)
-    if (entry.schema_fit !== undefined && entry.schema_fit > 0.7) {
-        hl *= 1.5;
-    }
-    // Low schema fit: decay faster (0.5x)
-    if (entry.schema_fit !== undefined && entry.schema_fit < 0.3) {
-        hl *= 0.5;
-    }
-    return hl;
-}
-/**
- * Apply outcome feedback to a memory entry.
- *
- * Increments outcome_positive or outcome_negative counters.
- * The reward factor in calculateStrength() uses these counts to
- * continuously modulate the effective half-life:
- *   reward_ratio  = (pos - neg) / (pos + neg + 1)
- *   reward_factor = 1 + 0.5 * reward_ratio    // range (0.5, 1.5)
- *   effective_hl  = half_life_days * reward_factor
- *
- * No fixed half-life delta. Decay rate adjusts proportionally to
- * cumulative reward signal, inspired by R-STDP in spiking networks.
- */
-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) };
-}
-/**
- * Generate a random memory ID using crypto.randomUUID().
- */
-export function generateId(prefix = 'mem') {
-    return `${prefix}_${randomUUID().replace(/-/g, '').slice(0, 12)}`;
-}
-// Pinned and verified are exempt from ageing by policy, so this reads "aged out
-// for trust purposes", not "old". The 30-day threshold lives here and nowhere else.
-function isAgedOut(entry, now) {
-    if (entry.pinned || entry.confidence === 'verified')
-        return false;
-    const lastRetrieved = new Date(entry.last_retrieved);
-    return (now.getTime() - lastRetrieved.getTime()) / (1000 * 60 * 60 * 24) > 30;
-}
-export function confidenceFacets(entry, now = evalNow()) {
-    return { tier: entry.confidence, agedOut: isAgedOut(entry, now) };
-}
-// `warn` covers exactly the rows the old collapsed-value rule did: an aged-out row
-// used to read 'stale', so warning on it separately keeps the same set.
-export function confidenceLabel(entry, now = evalNow()) {
-    const { tier, agedOut } = confidenceFacets(entry, now);
-    return {
-        text: agedOut ? `${tier}, aged` : tier,
-        warn: agedOut || tier === 'stale' || tier === 'inferred',
-    };
-}
-/**
- * Resolve the effective confidence for a memory entry.
- * If the entry has not been retrieved in 30+ days and is not 'verified',
- * returns 'stale'. Otherwise returns the stored confidence value.
- */
-export function resolveConfidence(entry, now = evalNow()) {
-    return isAgedOut(entry, now) ? 'stale' : entry.confidence;
-}
-/**
- * Base half-life for a new memory, in days, before `deriveHalfLife`'s
- * write-time multipliers. 365 because 7 days lost the current fact far more
- * often, and 730 days or no decay did no better. `hippo sleep` moves memories still
- * on an older base (src/half-life-migration.ts).
- */
-export const DEFAULT_HALF_LIFE_DAYS = 365;
-export const COMPACTION_MEMORY_TAG = 'compaction-memory';
-export const COMPACTION_SOURCE_PREFIX = 'compaction:';
-export const KEEP_PAIRS = AGENT_MEMORY_TOOLS.map((t) => ({ tag: t.tag, sourcePrefix: toolSourcePrefix(t.id) }));
-const sqlText = (s) => `'${s.replace(/'/g, "''")}'`;
-// json_each matches the tag as a whole element; substr, not LIKE, keeps the prefix case-sensitive like startsWith.
-const keepPairSql = (p) => `(COALESCE(superseded_by, '') = '' AND EXISTS (SELECT 1 FROM json_each(CASE WHEN json_valid(tags_json) THEN tags_json ELSE '[]' END) WHERE value = ${sqlText(p.tag)}) AND substr(source, 1, ${p.sourcePrefix.length}) = ${sqlText(p.sourcePrefix)})`;
-// Pinned and kept rows stay (a superseded row is not kept: its successor carries the tag and source); raw rows leave only through archiveRawMemory. The SQL twin guards the DELETE itself.
-export const AUTO_DELETABLE_SQL = `pinned = 0 AND kind != 'raw'${KEEP_PAIRS.map((p) => ` AND NOT ${keepPairSql(p)}`).join('')}`;
-export function isKeptForGood(entry) {
-    return !entry.superseded_by && KEEP_PAIRS.some((p) => entry.tags.includes(p.tag) && entry.source.startsWith(p.sourcePrefix));
-}
-export function canAutoDelete(entry) {
-    return !entry.pinned && entry.kind !== 'raw' && !isKeptForGood(entry);
-}
-export function createMemory(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.`);
-    }
-    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 ?? 0.5;
-    const partial = { tags, schema_fit };
-    const half_life_days = deriveHalfLife(options.baseHalfLifeDays ?? DEFAULT_HALF_LIFE_DAYS, partial);
-    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',
-    };
-    // Recalculate strength with the emotional multiplier applied
-    entry.strength = calculateStrength(entry);
-    return entry;
-}
-/** 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 (typeof old.origin_project === 'string') {
-        next.origin_project = old.origin_project;
-    }
-    return next;
-}
-/**
- * Compute how well new content fits existing knowledge patterns.
- * Returns 0..1 where:
- *   >0.7 = high fit (consistent with existing knowledge, consolidates faster)
- *   0.3-0.7 = moderate fit
- *   <0.3 = novel (doesn't match existing patterns, decays faster if unused)
- *
- * Uses tag overlap (always available) weighted by how common each tag is.
- * Rare shared tags signal stronger schema fit than common ones.
- */
-export function computeSchemaFit(content, tags, existingEntries) {
-    if (existingEntries.length === 0)
-        return 0.5; // no schema yet, neutral
-    // Build tag frequency map across all existing entries
-    const tagFreq = new Map();
-    for (const entry of existingEntries) {
-        for (const tag of entry.tags) {
-            tagFreq.set(tag, (tagFreq.get(tag) ?? 0) + 1);
-        }
-    }
-    if (tags.length === 0 && tagFreq.size === 0)
-        return 0.5;
-    // Tag overlap: IDF-weighted Jaccard
-    // Shared rare tags matter more than shared common tags
-    let weightedOverlap = 0;
-    let totalWeight = 0;
-    const N = existingEntries.length;
-    for (const tag of tags) {
-        const freq = tagFreq.get(tag) ?? 0;
-        // IDF-weighted: rare shared tags score higher
-        const maxIdf = Math.log(N + 1) + 1;
-        if (freq > 0) {
-            const idf = Math.log(N / freq) + 1;
-            weightedOverlap += idf;
-        }
-        totalWeight += maxIdf;
-    }
-    // Scale so that matching half the tags at average IDF gives ~0.5
-    const tagScore = totalWeight > 0 ? Math.min(1, (weightedOverlap / totalWeight) * 2) : 0;
-    // Content overlap: check how many existing entries share significant tokens
-    const newTokens = new Set(content.toLowerCase().replace(/[^\w\s]/g, ' ').split(/\s+/).filter((t) => t.length > 3));
-    if (newTokens.size === 0)
-        return Math.min(1, Math.max(0, tagScore));
-    let contentMatches = 0;
-    for (const entry of existingEntries) {
-        const entryTokens = new Set(entry.content.toLowerCase().replace(/[^\w\s]/g, ' ').split(/\s+/).filter((t) => t.length > 3));
-        let shared = 0;
-        for (const token of newTokens) {
-            if (entryTokens.has(token))
-                shared++;
-        }
-        const overlap = shared / Math.max(newTokens.size, 1);
-        if (overlap > 0.2)
-            contentMatches++;
-    }
-    const contentScore = Math.min(1, contentMatches / Math.max(5, N * 0.1));
-    // Blend: 60% tag overlap, 40% content overlap
-    const fit = 0.6 * tagScore + 0.4 * 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';
-}
-/**
- * Update retrieval metadata on entries that were returned by a search.
- * Returns the mutated copies (caller must persist to disk).
- *
- * EVAL-ONLY ablation (see ablation.ts): with HIPPO_ABLATE_RECALL_BOOST set,
- * this returns the entries UNMUTATED - neutralizing all three strengthening
- * sub-effects (clock reset, retrieval_count, half-life increment) at the
- * single shared write site. The entries (not an empty array) must be
- * returned because callers derive `last_retrieval_ids` from the return
- * value, and a later `hippo outcome --good/--bad` targets those ids - an
- * empty return would silently co-ablate the outcome channel in the
- * strengthen-off arm. PERSISTENCE is gated separately at
- * each persisting caller (CLI recall, api context, MCP recall/context,
- * consolidation replay): writeEntry on identical rows still refreshes
- * updated_at, rewrites mirrors, and marks DAG parents dirty,
- * so those write loops skip under the flag.
- * The default `now` honors HIPPO_FAKE_NOW (simulated-time protocols).
- */
-// Confidence is deliberately absent below: it is an epistemic tier, not a
-// recency signal, and a stored 'stale' is always a deliberate mark.
-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;
-        const updated = {
-            ...e,
-            retrieval_count: e.retrieval_count + 1,
-            last_retrieved: wrong ? e.last_retrieved : now.toISOString(),
-            // +2 days half-life per retrieval (PLAN.md); a wrong memory keeps both, since last_retrieved is the decay anchor
-            half_life_days: wrong ? e.half_life_days : e.half_life_days + 2,
-        };
-        updated.strength = calculateStrength(updated, now);
-        return updated;
-    });
-}
-//# sourceMappingURL=memory.js.map

package/dist/owner-validation.d.ts

@@ -1,42 +0,0 @@
-/**
- * --owner format validation.
- *
- * Documented MEMORY_ENVELOPE.md contract: owner = `user:<id>` | `agent:<id>`
- * with id ∈ `[A-Za-z0-9_-]+`.
- *
- * Default: WARN-ONLY (log + accept) to preserve back-compat with existing
- * scripted callers passing legacy owner strings. Set `HIPPO_STRICT_OWNER=1`
- * to reject + exit. Strict mode will become the default once real auth replaces
- * the stub (see `TODOS.md` for the migration path).
- */
-export declare const OWNER_RE: RegExp;
-export declare const OWNER_CONTRACT_HINT = "Must match ^(user|agent):[A-Za-z0-9_-]+$ (e.g. user:alice, agent:capture-bot).";
-export interface OwnerValidation {
-    ok: boolean;
-    /** The owner string as the caller should now use it. undefined when no owner was supplied. */
-    value: string | undefined;
-    /** Human-readable message (warn or error). Empty when ok = true. */
-    message: string;
-}
-/**
- * Pure validator. Returns `{ ok, value, message }`. Does NOT print or
- * `process.exit`. The CLI wrapper below handles side effects so this is
- * unit-testable.
- *
- * Behaviour:
- *   - owner undefined → ok=true, value=undefined, no message.
- *   - owner matches OWNER_RE → ok=true, value=owner.
- *   - owner doesn't match + strict=false → ok=true, value=owner (accept),
- *     message contains the warning text.
- *   - owner doesn't match + strict=true → ok=false, value=owner (echoed),
- *     message contains the error text.
- */
-export declare function validateOwner(owner: string | null | undefined, opts?: {
-    strict?: boolean;
-}): OwnerValidation;
-/**
- * Returns true when strict-owner enforcement is enabled via env var.
- * Centralised here so any future bump to default-strict is one edit.
- */
-export declare function isStrictOwnerEnv(env?: NodeJS.ProcessEnv): boolean;
-//# sourceMappingURL=owner-validation.d.ts.map

package/dist/owner-validation.js

@@ -1,56 +0,0 @@
-/**
- * --owner format validation.
- *
- * Documented MEMORY_ENVELOPE.md contract: owner = `user:<id>` | `agent:<id>`
- * with id ∈ `[A-Za-z0-9_-]+`.
- *
- * Default: WARN-ONLY (log + accept) to preserve back-compat with existing
- * scripted callers passing legacy owner strings. Set `HIPPO_STRICT_OWNER=1`
- * to reject + exit. Strict mode will become the default once real auth replaces
- * the stub (see `TODOS.md` for the migration path).
- */
-import { processEnv } from './env.js';
-export const OWNER_RE = /^(user|agent):[A-Za-z0-9_-]+$/;
-export const OWNER_CONTRACT_HINT = 'Must match ^(user|agent):[A-Za-z0-9_-]+$ (e.g. user:alice, agent:capture-bot).';
-/**
- * Pure validator. Returns `{ ok, value, message }`. Does NOT print or
- * `process.exit`. The CLI wrapper below handles side effects so this is
- * unit-testable.
- *
- * Behaviour:
- *   - owner undefined → ok=true, value=undefined, no message.
- *   - owner matches OWNER_RE → ok=true, value=owner.
- *   - owner doesn't match + strict=false → ok=true, value=owner (accept),
- *     message contains the warning text.
- *   - owner doesn't match + strict=true → ok=false, value=owner (echoed),
- *     message contains the error text.
- */
-export function validateOwner(owner, opts = {}) {
-    if (owner === undefined || owner === null || owner === '') {
-        return { ok: true, value: undefined, message: '' };
-    }
-    if (OWNER_RE.test(owner)) {
-        return { ok: true, value: owner, message: '' };
-    }
-    if (opts.strict) {
-        return {
-            ok: false,
-            value: owner,
-            message: `Invalid --owner "${owner}". ${OWNER_CONTRACT_HINT}`,
-        };
-    }
-    return {
-        ok: true,
-        value: owner,
-        message: `[warn] --owner "${owner}" does not match the contract. ${OWNER_CONTRACT_HINT} ` +
-            `Accepting for back-compat; set HIPPO_STRICT_OWNER=1 to reject.`,
-    };
-}
-/**
- * Returns true when strict-owner enforcement is enabled via env var.
- * Centralised here so any future bump to default-strict is one edit.
- */
-export function isStrictOwnerEnv(env = processEnv()) {
-    return env.HIPPO_STRICT_OWNER === '1';
-}
-//# sourceMappingURL=owner-validation.js.map

package/dist/path-context.d.ts

@@ -1,24 +0,0 @@
-/**
- * Extract meaningful path segments from a directory path.
- * Returns tags like ['path:src', 'path:api', 'path:my-project'].
- * Filters out noise (node_modules, .git, Users, home dirs, drive letters).
- */
-export declare function extractPathTags(dirPath: string): string[];
-/**
- * Compute path overlap score between two sets of path tags.
- * Returns 0..1 where 1 = perfect match.
- * Normalizes by the MORE SPECIFIC side (the larger of the two tag sets),
- * so a memory carrying only a bare/generic path tag can no longer score a
- * full 1.0 against a deeply-nested cwd just because its own tiny tag set
- * is fully contained in the query's — genericity is no longer rewarded.
- */
-export declare function pathOverlapScore(memoryPathTags: string[], currentPathTags: string[]): number;
-/** Weight applied to path overlap score when computing the recall boost multiplier. */
-export declare const PATH_BOOST_WEIGHT = 0.3;
-/**
- * Multiplier applied to a composite recall score for path locality.
- * Filters the memory's tags to path:* itself so call sites cannot drift.
- * Returns 1.0..1.3.
- */
-export declare function pathBoostMultiplier(memoryTags: string[], currentPathTags: string[]): number;
-//# sourceMappingURL=path-context.d.ts.map