hippo-memory 1.68.0 → 1.70.0

package/dist/core/handoff.js

@@ -0,0 +1,87 @@
+/**
+ * Session handoff types and helpers.
+ *
+ * A handoff captures the state of a session so that a successor
+ * session (or a different agent) can pick up where the previous
+ * one left off.
+ */
+import { isJsonString } from '../util/json.js';
+import { warnDamagedColumn } from '../util/stored-json.js';
+/** Narrows an unvalidated value (e.g. CLI input or event content) to a HandoffOutcome. */
+export function isHandoffOutcome(v) {
+    return v === 'success' || v === 'failure' || v === 'partial';
+}
+/** Renders evidence as one line shared by every renderer (CLI, MCP, token accounting). */
+export function formatHandoffEvidenceLine(evidence) {
+    const gitRef = evidence.gitRef ?? 'unknown';
+    const tree = evidence.dirtyTree === true ? 'dirty' : evidence.dirtyTree === false ? 'clean' : 'unknown';
+    const tests = evidence.testStatus ?? 'unknown';
+    return `git ${gitRef}, tree ${tree}, tests ${tests}`;
+}
+const TEST_STATUSES = new Set(['pass', 'fail', 'unknown']);
+const absent = (v) => v === undefined || v === null;
+function isHandoffEvidence(v) {
+    if (!(v instanceof Object) || Array.isArray(v))
+        return false;
+    const { gitRef, dirtyTree, testStatus, derivedFrom } = v;
+    return (absent(gitRef) || isJsonString(gitRef))
+        && (absent(dirtyTree) || dirtyTree === true || dirtyTree === false)
+        && (absent(testStatus) || TEST_STATUSES.has(testStatus))
+        && (derivedFrom === undefined || derivedFrom === 'transcript');
+}
+/** A stored list column as strings; a damaged one logs and reads as empty instead of hiding the whole handoff. */
+function storedList(row, column) {
+    const raw = row[column];
+    if (!raw)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed.map((item) => String(item)) : [];
+    }
+    catch {
+        warnDamagedColumn({ table: 'session_handoffs', id: row.id, column }, 'not valid JSON');
+        return [];
+    }
+}
+/** Stored evidence, or null (after a log line) when the column is damaged or holds another shape. */
+function storedEvidence(row) {
+    if (!row.evidence_json)
+        return null;
+    const site = { table: 'session_handoffs', id: row.id, column: 'evidence_json' };
+    let parsed;
+    try {
+        parsed = JSON.parse(row.evidence_json);
+    }
+    catch {
+        warnDamagedColumn(site, 'not valid JSON');
+        return null;
+    }
+    if (parsed === null)
+        return null;
+    if (isHandoffEvidence(parsed))
+        return parsed;
+    warnDamagedColumn(site, 'wrong shape');
+    return null;
+}
+export function rowToSessionHandoff(row) {
+    const artifacts = storedList(row, 'artifacts_json');
+    const constraints = storedList(row, 'constraints_json');
+    const evidence = storedEvidence(row);
+    return {
+        version: 1,
+        sessionId: row.session_id,
+        repoRoot: row.repo_root ?? undefined,
+        taskId: row.task_id ?? undefined,
+        summary: row.summary,
+        nextAction: row.next_action ?? undefined,
+        artifacts,
+        scope: row.scope ?? null,
+        updatedAt: row.created_at,
+        constraints,
+        evidence,
+        outcome: isHandoffOutcome(row.outcome) ? row.outcome : null,
+        targetRuntime: row.target_runtime ?? null,
+        cardId: row.card_id ?? null,
+    };
+}
+//# sourceMappingURL=handoff.js.map

package/dist/{memory-quality.js → core/memory-quality.js}

@@ -1,5 +1,5 @@
 import { COMPACTION_MEMORY_TAG, COMPACTION_SOURCE_PREFIX } from './memory.js';
-import { heldTexts } from './same-text.js';
+import { heldTexts } from '../util/same-text.js';
 export const STOP_WORDS = new Set([
     'the', 'a', 'an', 'is', 'was', 'are', 'were', 'be', 'been', 'being',
     'to', 'of', 'in', 'for', 'on', 'with', 'at', 'by', 'from', 'it',

package/dist/{memory.d.ts → core/memory.d.ts}

@@ -2,6 +2,8 @@
  * 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",
@@ -122,7 +124,7 @@ export declare const CHURN_STALE_TAG = "churn-stale";
  *     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.
+ * See `tests/emotional-multipliers.test.ts` for the pattern.
  */
 export declare function _resetLossAversionRatioCacheForTests(): void;
 /**
@@ -172,9 +174,6 @@ export declare function calculateStrength(entry: StrengthInputs, now?: Date, opt
 /** 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 declare function strengthSql(now: Date): string;
-/**
- * Derive half-life based on signals, as per PLAN.md table.
- */
 export declare function deriveHalfLife(base: number, entry: Partial<MemoryEntry>): number;
 /**
  * Apply outcome feedback to a memory entry.
@@ -190,15 +189,20 @@ export declare function deriveHalfLife(base: number, entry: Partial<MemoryEntry>
  * cumulative reward signal, inspired by R-STDP in spiking networks.
  */
 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;
 /**
  * Generate a random memory ID using crypto.randomUUID().
  */
 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;
@@ -213,7 +217,7 @@ export declare function resolveConfidence(entry: MemoryEntry, now?: Date): Confi
  * 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).
+ * 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";
@@ -270,6 +274,16 @@ export declare function createSuccessor(old: MemoryEntry, content: string, opts:
  * Rare shared tags signal stronger schema fit than common ones.
  */
 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;
 /**
  * Update retrieval metadata on entries that were returned by a search.
  * Returns the mutated copies (caller must persist to disk).

package/dist/{memory.js → core/memory.js}

@@ -2,11 +2,15 @@
  * Core data model for Hippo memory entries.
  * Based on the strength formula from PLAN.md.
  */
-import { envLossAversionRatio } from './env.js';
+import { 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-memories/tools.js';
+import { AGENT_MEMORY_TOOLS, toolSourcePrefix } from './agent-memory-tools.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";
@@ -92,7 +96,7 @@ function getLossAversionRatio() {
  *     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.
+ * See `tests/emotional-multipliers.test.ts` for the pattern.
  */
 export function _resetLossAversionRatioCacheForTests() {
     _lossAversionRatioCache = undefined;
@@ -127,10 +131,16 @@ export function calculateRewardFactor(entry) {
     if (pos === 0 && neg === 0)
         return 1.0;
     const ratio = (pos - neg) / (pos + neg + 1);
-    return 1 + 0.5 * ratio;
+    return 1 + REWARD_SLOPE * ratio;
 }
 /** Bad marks alone never push a memory under sleep's 0.05 retire line; supersede is the hard correction. */
 const MAX_WRONG_HALVINGS = 3;
+// Shared by calculateStrength and strengthSql so the two cannot drift.
+const DECAY_BASE = 0.5;
+const REWARD_SLOPE = 0.5;
+const RETRIEVAL_BOOST_SLOPE = 0.1;
+const SQL_DEFAULT_HALF_LIFE_DAYS = 7;
+const UNIX_EPOCH_JULIAN_DAY = 2440587.5;
 /**
  * Net wrongness: bad outcome marks past good ones, never below zero.
  * Strength halves per unit (capped at 3) and recall stops strengthening
@@ -157,58 +167,62 @@ export function calculateStrength(entry,
 // 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));
+    const wrongPenalty = Math.pow(DECAY_BASE, Math.min(netWrong(entry), MAX_WRONG_HALVINGS));
     if (entry.pinned)
         return wrongPenalty;
     // EVAL-ONLY ablation (see ablation.ts): anchor decay at CREATION, so clock resets persisted by PRIOR
     // unflagged runs cannot leak strengthening into an ablated arm. Prior-run half_life increments are
     // NOT reconstructed - see the ablation.ts caveat (fresh stores per arm).
     const lastRetrieved = new Date(isRecallBoostAblated() ? entry.created : entry.last_retrieved);
-    const daysSince = (now.getTime() - lastRetrieved.getTime()) / (1000 * 60 * 60 * 24);
+    const daysSince = (now.getTime() - lastRetrieved.getTime()) / DAY_MS;
     // Reward-proportional half-life modulation
     const rewardFactor = calculateRewardFactor(entry);
-    let effectiveHalfLife = entry.half_life_days * rewardFactor;
+    const effectiveHalfLife = entry.half_life_days * rewardFactor;
     // Guard: zero half-life causes 0/0 = NaN in the exponent
     if (effectiveHalfLife <= 0)
         return 0.0;
+    const decayExponent = decayExponentFor(options, daysSince, effectiveHalfLife);
+    // EVAL-ONLY ablation (see ablation.ts): decay term := 1. NOTE the [0,1]
+    // clamp below then caps retrievalBoost at baseline - see ablation.ts
+    // formula note.
+    const decay = isDecayAblated() ? 1.0 : Math.pow(DECAY_BASE, decayExponent);
+    const retrievalBoost = retrievalBoostFor(entry);
+    // Emotional multiplier. HIPPO_LOSS_AVERSION_RATIO scales the negative one ONLY; the lazy
+    // module cache makes this one lookup + one multiply, not a per-call process.env read.
+    const baseMultiplier = EMOTIONAL_MULTIPLIERS[entry.emotional_valence] ?? 1.0;
+    const emotionalMultiplier = applyLossAversionRatio(entry.emotional_valence, baseMultiplier);
+    const raw = decay * retrievalBoost * emotionalMultiplier;
+    // Clamp to [0, 1] with NaN guard
+    const clamped = Math.min(1.0, Math.max(0.0, raw));
+    return Number.isFinite(clamped) ? clamped * wrongPenalty : 0.0;
+}
+function decayExponentFor(options, daysSince, halfLifeDays) {
+    let effectiveHalfLife = halfLifeDays;
     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;
+        return sessionsSince / effectiveHalfLife;
     }
-    else if (basis === 'adaptive') {
+    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;
+        return 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
+    // clock: classic wall-clock decay
+    return daysSince / effectiveHalfLife;
+}
+// Retrieval boost: 1 + 0.1 * log2(retrieval_count + 1). EVAL-ONLY ablation (see ablation.ts) neutralizes
+// the READ side too, so counts written before the flag cannot leak strengthening into an ablated arm.
+function retrievalBoostFor(entry) {
+    return 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;
+        : 1 + RETRIEVAL_BOOST_SLOPE * Math.log2(entry.retrieval_count + 1);
 }
 /** calculateStrength's clock-basis formula as SQL over `memories` columns, flags and multipliers baked in; keep in step.
  *  An unparseable date scores NULL here and 0 in JS, so sums agree. */
@@ -219,25 +233,34 @@ export function strengthSql(now) {
     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})`;
+        : `(CASE WHEN ${pos} = 0 AND ${neg} = 0 THEN 1.0 ELSE 1.0 + ${REWARD_SLOPE} * (${pos} - ${neg}) / (${pos} + ${neg} + 1.0) END)`;
+    const halfLife = `(COALESCE(half_life_days, ${SQL_DEFAULT_HALF_LIFE_DAYS}) * ${reward})`;
     const anchor = isRecallBoostAblated() ? 'created' : 'last_retrieved';
-    const nowJulian = num(now.getTime() / 86400000 + 2440587.5);
-    const decay = isDecayAblated() ? '1.0' : `pow(0.5, (${nowJulian} - julianday(${anchor})) / ${halfLife})`;
+    const nowJulian = num(now.getTime() / DAY_MS + UNIX_EPOCH_JULIAN_DAY);
+    const decay = isDecayAblated() ? '1.0' : `pow(${DECAY_BASE}, (${nowJulian} - julianday(${anchor})) / ${halfLife})`;
     const boost = isRecallBoostAblated()
         ? '1.0'
-        : `(CASE WHEN ${wrong} > 0 THEN 1.0 ELSE 1.0 + 0.1 * log2(COALESCE(retrieval_count, 0) + 1) END)`;
+        : `(CASE WHEN ${wrong} > 0 THEN 1.0 ELSE 1.0 + ${RETRIEVAL_BOOST_SLOPE} * log2(COALESCE(retrieval_count, 0) + 1) END)`;
     const valences = /* SAFETY: a Record keyed by EmotionalValence */ Object.keys(EMOTIONAL_MULTIPLIERS);
     const emotion = `(CASE COALESCE(emotional_valence, 'neutral') ${valences
         .map((v) => `WHEN '${v}' THEN ${num(applyLossAversionRatio(v, EMOTIONAL_MULTIPLIERS[v]))}`)
         .join(' ')} ELSE 1.0 END)`;
-    const penalty = `pow(0.5, MIN(${wrong}, ${MAX_WRONG_HALVINGS}))`;
+    const penalty = `pow(${DECAY_BASE}, MIN(${wrong}, ${MAX_WRONG_HALVINGS}))`;
     return `(CASE WHEN pinned THEN ${penalty} WHEN ${halfLife} <= 0 THEN 0.0
     ELSE MIN(1.0, MAX(0.0, ${decay} * ${boost} * ${emotion})) * ${penalty} END)`;
 }
 /**
  * Derive half-life based on signals, as per PLAN.md table.
  */
+const HIGH_SCHEMA_FIT = 0.7;
+const HIGH_FIT_HALF_LIFE_FACTOR = 1.5;
+const LOW_SCHEMA_FIT = 0.3;
+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;
 export function deriveHalfLife(base, entry) {
     let hl = base;
     // Error-tagged: 2x half-life
@@ -245,12 +268,12 @@ export function deriveHalfLife(base, entry) {
         hl *= 2;
     }
     // High schema fit: consolidates faster (1.5x)
-    if (entry.schema_fit !== undefined && entry.schema_fit > 0.7) {
-        hl *= 1.5;
+    if (entry.schema_fit !== undefined && entry.schema_fit > HIGH_SCHEMA_FIT) {
+        hl *= HIGH_FIT_HALF_LIFE_FACTOR;
     }
     // Low schema fit: decay faster (0.5x)
-    if (entry.schema_fit !== undefined && entry.schema_fit < 0.3) {
-        hl *= 0.5;
+    if (entry.schema_fit !== undefined && entry.schema_fit < LOW_SCHEMA_FIT) {
+        hl *= LOW_FIT_HALF_LIFE_FACTOR;
     }
     return hl;
 }
@@ -277,21 +300,29 @@ export function applyOutcome(entry, good) {
     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)}`;
+    return `${prefix}_${randomUUID().replace(/-/g, '').slice(0, ID_SUFFIX_CHARS)}`;
 }
-// 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;
+    return (now.getTime() - lastRetrieved.getTime()) / DAY_MS > 30;
 }
 export function confidenceFacets(entry, now = evalNow()) {
+    return facetsOf(entry, now);
+}
+export function facetsOf(entry, now) {
     return { tier: entry.confidence, agedOut: isAgedOut(entry, now) };
 }
 // `warn` covers exactly the rows the old collapsed-value rule did: an aged-out row
@@ -315,7 +346,7 @@ export function resolveConfidence(entry, now = evalNow()) {
  * 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).
+ * on an older base (src/consolidate/half-life-migration.ts).
  */
 export const DEFAULT_HALF_LIFE_DAYS = 365;
 export const COMPACTION_MEMORY_TAG = 'compaction-memory';
@@ -333,21 +364,13 @@ 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.`);
-    }
+    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 ?? 0.5;
-    const partial = { tags, schema_fit };
-    const half_life_days = deriveHalfLife(options.baseHalfLifeDays ?? DEFAULT_HALF_LIFE_DAYS, partial);
+    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,
@@ -386,6 +409,16 @@ export function createMemory(content, options = {}) {
     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, {
@@ -416,53 +449,55 @@ export function createSuccessor(old, content, opts) {
  * 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();
+    const tagCounts = new Map();
     for (const entry of existingEntries) {
         for (const tag of entry.tags) {
-            tagFreq.set(tag, (tagFreq.get(tag) ?? 0) + 1);
+            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 0.5; // no schema yet, neutral
+    const tagFreq = source.tagCounts;
     if (tags.length === 0 && tagFreq.size === 0)
         return 0.5;
-    // Tag overlap: IDF-weighted Jaccard
-    // Shared rare tags matter more than shared common tags
+    // Tag overlap, weighted so a shared rare tag counts for more than a shared common one.
     let weightedOverlap = 0;
     let totalWeight = 0;
-    const N = existingEntries.length;
+    const maxIdf = Math.log(N + 1) + 1;
     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;
-        }
+        if (freq > 0)
+            weightedOverlap += Math.log(N / freq) + 1;
         totalWeight += maxIdf;
     }
-    // Scale so that matching half the tags at average IDF gives ~0.5
+    // 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;
-    // 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));
+    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 entry of existingEntries) {
-        const entryTokens = new Set(entry.content.toLowerCase().replace(/[^\w\s]/g, ' ').split(/\s+/).filter((t) => t.length > 3));
+    for (const text of source.contents) {
+        const entryTokens = significantTokens(text);
         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++;
+        if (shared / newTokens.size > CONTENT_TOKEN_SHARE_MIN && ++contentMatches >= enough)
+            break;
     }
-    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;
+    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) {

package/dist/{physics.d.ts → core/physics.d.ts}

@@ -9,7 +9,7 @@
  * conflict repulsion, and drag (consolidation). Nearby high-scoring memories
  * amplify each other via constructive interference.
  */
-import type { EmotionalValence } from './memory.js';
+import { type EmotionalValence } from './memory.js';
 import type { PhysicsConfig } from './physics-config.js';
 export interface PhysicsParticle {
     memoryId: string;

package/dist/{physics.js → core/physics.js}

@@ -10,6 +10,7 @@
  * amplify each other via constructive interference.
  */
 import { isRecallBoostAblated } from './ablation.js';
+import { FALLBACK_HALF_LIFE_DAYS } from './memory.js';
 import { comparePhysicsResultsBy } from './compare.js';
 // ---------------------------------------------------------------------------
 // Vector math (hot path — kept inline for performance)
@@ -183,7 +184,7 @@ function computeNetForce(i, particles, ctx) {
         }
     }
     // Drag
-    const fd = dragForce(pi, ctx.config.drag, ctx.halfLives.get(pi.memoryId) ?? 7);
+    const fd = dragForce(pi, ctx.config.drag, ctx.halfLives.get(pi.memoryId) ?? FALLBACK_HALF_LIFE_DAYS);
     net = vecAdd(net, fd);
     return net;
 }

package/dist/{project-identity.d.ts → core/project-identity.d.ts}

@@ -41,11 +41,6 @@ export interface ResolveProjectIdentityOpts {
 }
 /** Clear the per-process identity cache and the remote switch it read (test seam). */
 export declare function clearProjectIdentityCache(): void;
-/**
- * Canonicalize a path via realpath, falling back to path.resolve when the
- * path does not exist or realpath fails (mirrors importers.ts).
- */
-export declare function realpathOrResolve(p: string): string;
 /**
  * Resolve the project identity for a working directory.
  * Defaults to process.cwd(). Results are cached per resolved input path.

package/dist/{project-identity.js → core/project-identity.js}

@@ -1,12 +1,13 @@
-import { envHippoHome, envXdgDataHome } from './env.js';
+import { envHippoHome, envXdgDataHome } from '../util/env.js';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { BadRequestError } from './api-errors.js';
 import { isSharedStore, loadConfig } from './config.js';
-import { MAX_ID_LEN } from './http-util.js';
-import { log } from './log.js';
+import { MAX_ID_LEN } from '../util/http-util.js';
+import { errorMessage, log } from '../util/log.js';
 import { originRemoteId, projectFileId } from './project-remote.js';
+import { realpathOrResolve } from '../util/real-path.js';
 const MAX_WALK_DEPTH = 64;
 const identityCache = new Map();
 let remoteSwitch = null;
@@ -30,19 +31,6 @@ function namesAt(root, legacyName) {
     const aliases = [...new Set([fileId, remoteId, legacyName])].filter((n) => n !== null && n !== name);
     return aliases.length > 0 ? { name, aliases } : { name };
 }
-/**
- * Canonicalize a path via realpath, falling back to path.resolve when the
- * path does not exist or realpath fails (mirrors importers.ts).
- */
-export function realpathOrResolve(p) {
-    try {
-        return fs.realpathSync.native(p);
-    }
-    catch (err) {
-        log.debug(`project identity: realpath fell back to resolve for ${p}: ${err instanceof Error ? err.message : String(err)}`);
-        return path.resolve(p);
-    }
-}
 /** Compare two canonical paths, case-insensitively on Windows. */
 function samePath(a, b) {
     if (process.platform === 'win32')
@@ -68,7 +56,7 @@ function isDirectoryAt(p) {
         return fs.statSync(p).isDirectory();
     }
     catch (err) {
-        log.debug(`project identity: no marker at ${p}: ${err instanceof Error ? err.message : String(err)}`);
+        log.debug(`project identity: no marker at ${p}: ${errorMessage(err)}`);
         return false;
     }
 }

package/dist/{project-remote.js → core/project-remote.js}

@@ -2,7 +2,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { isObjectLike, isStringValue } from './capture-contract.js';
-import { log } from './log.js';
+import { errorMessage, log } from '../util/log.js';
 /** The config file git reads for a checkout: `.git/config`, a linked worktree's `<commondir>/config`, a submodule's `<gitdir>/config`. */
 export function gitConfigPath(gitRoot) {
     const marker = path.join(gitRoot, '.git');
@@ -19,7 +19,7 @@ export function gitConfigPath(gitRoot) {
         return path.join(path.resolve(linkDir, fs.readFileSync(commondir, 'utf8').trim()), 'config');
     }
     catch (err) {
-        log.debug(`project remote: no git config for ${gitRoot}: ${err instanceof Error ? err.message : String(err)}`);
+        log.debug(`project remote: no git config for ${gitRoot}: ${errorMessage(err)}`);
         return null;
     }
 }
@@ -111,7 +111,7 @@ export function originRemoteId(gitRoot) {
         return url === null ? null : normaliseRemote(url);
     }
     catch (err) {
-        log.debug(`project remote: ${file} not read: ${err instanceof Error ? err.message : String(err)}`);
+        log.debug(`project remote: ${file} not read: ${errorMessage(err)}`);
         return null;
     }
 }
@@ -131,7 +131,7 @@ export function projectFileId(root) {
         log.warn(`${file}: "id" must be a non-empty string with no colon, slash or spaces; using the remote or folder name instead`);
     }
     catch (err) {
-        log.warn(`${file} not read: ${err instanceof Error ? err.message : String(err)}; using the remote or folder name instead`);
+        log.warn(`${file} not read: ${errorMessage(err)}; using the remote or folder name instead`);
     }
     return null;
 }