hippo-memory 1.69.0 → 1.70.0

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

@@ -84,7 +84,7 @@
  * that mutate these env vars MUST call _resetAblationCacheForTests() in BOTH
  * beforeEach AND afterEach.
  */
-import { envAblateDecay, envAblateOutcome, envAblateOutcomeFast, envAblateOutcomeSlow, envAblateRecallBoost, envAblateRecency, envEvalRecencyDays, envFakeNowMs, } from './env.js';
+import { envAblateDecay, envAblateOutcome, envAblateOutcomeFast, envAblateOutcomeSlow, envAblateRecallBoost, envAblateRecency, envEvalRecencyDays, envFakeNowMs, } from '../util/env.js';
 let _cache;
 function readFlags() {
     if (_cache !== undefined)

package/dist/{agent-memories/tools.d.ts → core/agent-memory-tools.d.ts}

@@ -30,4 +30,4 @@ export declare const AGENT_MEMORY_SOURCE_PREFIX = "agent-memory:";
 export declare function toolSourcePrefix(id: ToolId): string;
 export declare const AGENT_MEMORY_TAGS: readonly string[];
 export declare function isToolId(value: string): value is ToolId;
-//# sourceMappingURL=tools.d.ts.map
+//# sourceMappingURL=agent-memory-tools.d.ts.map

package/dist/{agent-memories/tools.js → core/agent-memory-tools.js}

@@ -16,4 +16,4 @@ export const AGENT_MEMORY_TAGS = AGENT_MEMORY_TOOLS.map((t) => t.tag);
 export function isToolId(value) {
     return AGENT_MEMORY_TOOLS.some((t) => t.id === value);
 }
-//# sourceMappingURL=tools.js.map
+//# sourceMappingURL=agent-memory-tools.js.map

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

@@ -9,6 +9,8 @@
 import { evalNow } from './ablation.js';
 import { Layer } from './memory.js';
 import { calculateStrength } from './memory.js';
+import { DAY_MS } from '../util/time.js';
+const STATE_DECIMALS = 3;
 /** The tallies of two disjoint row sets taken together. */
 export function addAmbientTallies(a, b) {
     const tagCounts = new Map(a.tagCounts);
@@ -36,7 +38,7 @@ export function isErrorTagged(tags) {
 /** Tallies over loaded entries; superseded rows count toward the total only, as they always have here. */
 export function tallyAmbientEntries(entries, now) {
     const currentTime = now ?? evalNow(); // honors HIPPO_FAKE_NOW (eval-only)
-    const sevenDaysAgo = currentTime.getTime() - 7 * 86400000;
+    const sevenDaysAgo = currentTime.getTime() - 7 * DAY_MS;
     const t = {
         total: entries.length, strengthSum: 0, fresh: 0, negative: 0, highSchemaFit: 0, errors: 0,
         semantic: 0, episodic: 0, conflicts: 0, extracted: 0, maxDagLevel: 0, tagCounts: new Map(),
@@ -154,15 +156,15 @@ export function renderAmbientSummary(state) {
 export function formatAmbientVector(state) {
     const lines = [];
     lines.push('Ambient State Vector:');
-    lines.push(`  tag_entropy:          ${state.tagEntropy.toFixed(3)}`);
-    lines.push(`  avg_strength:         ${state.avgStrength.toFixed(3)}`);
-    lines.push(`  recency_freshness:    ${state.recencyFreshness.toFixed(3)}`);
-    lines.push(`  emotional_skew:       ${state.emotionalSkew.toFixed(3)}`);
-    lines.push(`  schema_fit_ratio:     ${state.schemaFitRatio.toFixed(3)}`);
-    lines.push(`  error_density:        ${state.errorDensity.toFixed(3)}`);
-    lines.push(`  consolidation_ratio:  ${state.consolidationRatio.toFixed(3)}`);
-    lines.push(`  conflict_intensity:   ${state.conflictIntensity.toFixed(3)}`);
-    lines.push(`  extraction_coverage:  ${state.extractionCoverage.toFixed(3)}`);
+    lines.push(`  tag_entropy:          ${state.tagEntropy.toFixed(STATE_DECIMALS)}`);
+    lines.push(`  avg_strength:         ${state.avgStrength.toFixed(STATE_DECIMALS)}`);
+    lines.push(`  recency_freshness:    ${state.recencyFreshness.toFixed(STATE_DECIMALS)}`);
+    lines.push(`  emotional_skew:       ${state.emotionalSkew.toFixed(STATE_DECIMALS)}`);
+    lines.push(`  schema_fit_ratio:     ${state.schemaFitRatio.toFixed(STATE_DECIMALS)}`);
+    lines.push(`  error_density:        ${state.errorDensity.toFixed(STATE_DECIMALS)}`);
+    lines.push(`  consolidation_ratio:  ${state.consolidationRatio.toFixed(STATE_DECIMALS)}`);
+    lines.push(`  conflict_intensity:   ${state.conflictIntensity.toFixed(STATE_DECIMALS)}`);
+    lines.push(`  extraction_coverage:  ${state.extractionCoverage.toFixed(STATE_DECIMALS)}`);
     lines.push(`  dag_depth:            ${state.dagDepth}`);
     lines.push(`  total_memories:       ${state.totalMemories}`);
     return lines.join('\n');

package/dist/{capture-contract.d.ts → core/capture-contract.d.ts}

@@ -13,13 +13,20 @@ export interface CaptureInput {
     readonly trigger: string | null;
 }
 /** The outcome of reading a payload: usable input, a payload hippo refuses, or no payload at all. */
-export type CaptureReceipt = {
+export type CaptureReceipt<I extends CaptureInput = CaptureInput> = {
     readonly status: 'received';
-    readonly input: CaptureInput;
+    readonly input: I;
 } | {
     readonly status: 'skipped' | 'unavailable';
     readonly reason: string;
 };
+/** What a PostCompact payload adds: it always names a session, and carries the summary Claude Code wrote. */
+export interface PostCompactInput extends CaptureInput {
+    readonly event: 'post-compact';
+    readonly sessionId: string;
+    /** null when Claude Code sent none; the transcript fills the record later. */
+    readonly compactSummary: string | null;
+}
 /** Working state saved before the host drops context, so the session can resume; it is not a lesson. */
 export interface Checkpoint {
     readonly runtime: string;
@@ -48,4 +55,8 @@ export type HookRuntime = 'claude-code' | 'copilot';
 export declare function readClaudeCodePreCompact(stdinText: string | undefined, timedOut: boolean, runtime?: HookRuntime): CaptureReceipt;
 /** Reads VS Code's per-reply Stop payload. Pass the raw stdin: stdin.ts would give a Copilot CLI agentStop the same snake_case keys. */
 export declare function readVscodeStop(stdinText: string | undefined, timedOut: boolean): CaptureReceipt;
+/** Reads a Claude Code PostCompact payload; it must name a session, but needs no transcript_path. */
+export declare function readClaudeCodePostCompact(stdinText: string | undefined, timedOut: boolean): CaptureReceipt<PostCompactInput>;
+/** Reads a Claude Code SessionEnd payload, or a Copilot one after stdin.ts mapped it to the same snake_case keys; only an empty stdin counts as a manual run. */
+export declare function readSessionEnd(stdinText: string | undefined, timedOut: boolean, runtime?: HookRuntime): CaptureReceipt;
 //# sourceMappingURL=capture-contract.d.ts.map

package/dist/{capture-contract.js → core/capture-contract.js}

@@ -82,4 +82,68 @@ export function readVscodeStop(stdinText, timedOut) {
         },
     };
 }
+/** Reads a Claude Code PostCompact payload; it must name a session, but needs no transcript_path. */
+export function readClaudeCodePostCompact(stdinText, timedOut) {
+    const empty = !stdinText || stdinText.trim() === '';
+    if (timedOut && empty) {
+        return { status: 'unavailable', reason: 'no PostCompact payload arrived before the stdin wait window closed' };
+    }
+    let payload;
+    try {
+        payload = empty ? undefined : JSON.parse(stdinText.trim());
+    }
+    catch {
+        // Non-JSON stdin leaves payload undefined, which the shape check rejects.
+    }
+    if (!isObjectLike(payload) || !('session_id' in payload) || !isStringValue(payload.session_id) || payload.session_id === '') {
+        return { status: 'skipped', reason: 'no PostCompact payload naming a session' };
+    }
+    return {
+        status: 'received',
+        input: {
+            runtime: 'claude-code',
+            event: 'post-compact',
+            manual: false,
+            sessionId: payload.session_id,
+            cwd: 'cwd' in payload && isStringValue(payload.cwd) ? payload.cwd : null,
+            transcriptPath: 'transcript_path' in payload && isStringValue(payload.transcript_path) ? payload.transcript_path : null,
+            trigger: 'trigger' in payload && isStringValue(payload.trigger) ? payload.trigger : null,
+            compactSummary: 'compact_summary' in payload && isStringValue(payload.compact_summary) ? payload.compact_summary : null,
+        },
+    };
+}
+/** Reads a Claude Code SessionEnd payload, or a Copilot one after stdin.ts mapped it to the same snake_case keys; only an empty stdin counts as a manual run. */
+export function readSessionEnd(stdinText, timedOut, runtime = 'claude-code') {
+    const empty = !stdinText || stdinText.trim() === '';
+    if (timedOut && empty) {
+        return { status: 'unavailable', reason: 'no SessionEnd payload arrived before the stdin wait window closed' };
+    }
+    const base = { runtime, event: 'session-end' };
+    if (empty) {
+        return { status: 'received', input: { ...base, manual: true, sessionId: null, cwd: null, transcriptPath: null, trigger: null } };
+    }
+    let payload;
+    try {
+        payload = JSON.parse(stdinText.trim());
+    }
+    catch {
+        // Non-JSON stdin leaves payload undefined, which the shape check rejects.
+    }
+    // Explicit array check: this reader has no required key to reject an array for it.
+    if (!isObjectLike(payload) || Array.isArray(payload)) {
+        return { status: 'skipped', reason: 'malformed SessionEnd payload (not a JSON object)' };
+    }
+    return {
+        status: 'received',
+        input: {
+            ...base,
+            manual: false,
+            sessionId: 'session_id' in payload && isStringValue(payload.session_id) && payload.session_id !== '' ? payload.session_id : null,
+            cwd: 'cwd' in payload && isStringValue(payload.cwd) ? payload.cwd : null,
+            transcriptPath: 'transcript_path' in payload && isStringValue(payload.transcript_path) && payload.transcript_path !== '' ? payload.transcript_path : null,
+            // Both hosts name a session end's trigger `reason`.
+            trigger: 'reason' in payload && isStringValue(payload.reason) ? payload.reason : null,
+        },
+    };
+}
 //# sourceMappingURL=capture-contract.js.map

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

@@ -64,6 +64,8 @@ export interface ScoredEntryLike {
  * the tiebreak can't silently drift between call sites.
  */
 export declare function compareScoredResults(a: ScoredEntryLike, b: ScoredEntryLike): number;
+/** Larger first, NaN after every number, 0 for equal scores. Not a subtraction: two infinities, or any NaN, subtract to NaN, which a sort reads as a tie. */
+export declare function compareScoresDesc(a: number, b: number): number;
 /**
  * Build a score-desc -> tie-key comparator for the physics layer.
  *

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

@@ -79,8 +79,15 @@ function compareTags(a, b) {
  * the tiebreak can't silently drift between call sites.
  */
 export function compareScoredResults(a, b) {
-    const d = b.score - a.score;
-    return d !== 0 ? d : compareEntryIdentity(a.entry, b.entry);
+    return compareScoresDesc(a.score, b.score) || compareEntryIdentity(a.entry, b.entry);
+}
+/** Larger first, NaN after every number, 0 for equal scores. Not a subtraction: two infinities, or any NaN, subtract to NaN, which a sort reads as a tie. */
+export function compareScoresDesc(a, b) {
+    if (a > b)
+        return -1;
+    if (a < b)
+        return 1;
+    return Number(Number.isNaN(a)) - Number(Number.isNaN(b));
 }
 /**
  * Build a score-desc -> tie-key comparator for the physics layer.
@@ -100,7 +107,7 @@ export function compareScoredResults(a, b) {
  */
 export function comparePhysicsResultsBy(scoreOf, tieKeyOf) {
     return (a, b) => {
-        const d = scoreOf(b) - scoreOf(a);
+        const d = compareScoresDesc(scoreOf(a), scoreOf(b));
         if (d !== 0)
             return d;
         const ai = tieKeyOf ? tieKeyOf(a) : a.memoryId;

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

@@ -22,7 +22,7 @@ export interface HippoConfig {
         /** Embedding backend. 'local' (default) = zero-dependency transformers.js.
          *  'openai' | 'voyage' | 'cohere' = opt-in API embedder; needs the provider's
          *  API key in env (OPENAI_API_KEY / VOYAGE_API_KEY / COHERE_API_KEY).
-         *  See src/embedding-provider.ts. */
+         *  See src/store/embeddings/provider.ts. */
         provider?: 'local' | 'openai' | 'voyage' | 'cohere';
         /** Optional API base-URL override (self-host / proxy). HTTPS only (localhost
          *  may use http). Ignored by the local provider. */
@@ -110,11 +110,11 @@ export interface HippoConfig {
         enabled: boolean;
     };
     /** Opt-in learned memory-value rescue veto on the sleep decay pass. Default OFF: the frozen weights
-     *  (src/memory-value-weights.ts) only run when enabled; the rescue budget is a code constant, not user-tunable. */
+     *  (src/consolidate/memory-value-weights.ts) only run when enabled; the rescue budget is a code constant, not user-tunable. */
     memoryValue: {
         enabled: boolean;
     };
-    /** Dormant memories (src/dormant.ts): when enabled (the default), the
+    /** Dormant memories (src/store/dormant.ts): when enabled (the default), the
      *  sleep decay pass moves a memory that faded below the threshold into the
      *  dormant store instead of deleting it. A dormant memory leaves recall and
      *  context like a deleted one, but `hippo dormant restore <id>` brings it
@@ -136,12 +136,12 @@ export interface HippoConfig {
     agentMemories: {
         tools: string[] | null;
     };
-    /** Per-turn delivery ledger (src/recall-trace.ts): hashes, ids, counts and rejection reasons for each
+    /** Per-turn delivery ledger (src/store/recall-trace.ts): hashes, ids, counts and rejection reasons for each
      *  pinned-only context call. Default off; read from the store the token ledger writes to. */
     deliveryLedger: {
         enabled: boolean;
     };
-    /** Pilot holdout (src/pilot-arm.ts): share of sessions, in basis points 0-10000, that get no memories pushed.
+    /** Pilot holdout (src/api/pilot-arm.ts): share of sessions, in basis points 0-10000, that get no memories pushed.
      *  Default 0 = off. Read from the store the token ledger writes to. */
     pilot: {
         holdoutRateBp: number;
@@ -157,7 +157,7 @@ export interface HippoConfig {
 }
 export declare function loadConfig(hippoRoot: string): HippoConfig;
 /** True when the store's config.json sets `"sharedStore": true`. Once true, a root stays true for this process,
- *  so a broken edit while a server runs cannot turn it off. Reads only this key: loadConfig has no cache. */
+ *  so a broken edit while a server runs cannot turn it off. Reads only this key, so loadConfig's warnings stay loadConfig's. */
 export declare function isSharedStore(hippoRoot: string): boolean;
 /** Reads the root as shared for the rest of this process, whatever its config.json says. */
 export declare function markSharedStore(hippoRoot: string): void;

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

@@ -5,8 +5,9 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { DEFAULT_PHYSICS_CONFIG, mergePhysicsConfig } from './physics-config.js';
 import { DEFAULT_HALF_LIFE_DAYS } from './memory.js';
-import { DEFAULT_LOCAL_BUMP, DEFAULT_RECALL_BUDGET } from './search/types.js';
-import { log } from './log.js';
+import { DEFAULT_LOCAL_BUMP, DEFAULT_RECALL_BUDGET } from './search-types.js';
+import { errorMessage, log } from '../util/log.js';
+import { isJsonObject } from '../util/json.js';
 const DEFAULT_CONFIG = {
     defaultHalfLifeDays: DEFAULT_HALF_LIFE_DAYS,
     defaultBudget: DEFAULT_RECALL_BUDGET,
@@ -98,23 +99,11 @@ const DEFAULT_CONFIG = {
     },
     sharedStore: false,
 };
-function isMemoryValueConfig(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-function isDormantConfig(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-function isChurnStalenessConfig(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-function isDeliveryLedgerConfig(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 // Only `{"enabled": true}` turns it on; anything malformed warns and stays off.
 function deliveryLedgerEnabled(value) {
     if (value === undefined)
         return false;
-    const isObject = isDeliveryLedgerConfig(value);
+    const isObject = isJsonObject(value);
     const enabled = isObject ? value.enabled : undefined;
     if (enabled === true || enabled === false)
         return enabled;
@@ -161,23 +150,23 @@ function memoryValueOverride(raw) {
     // Spreading a non-object raw.memoryValue (e.g. {"memoryValue": true}) silently leaves `enabled` false;
     // this feature must never be silently off, so warn loudly and fall back to defaults instead.
     const memoryValueRaw = raw.memoryValue;
-    const validMemoryValueConfig = memoryValueRaw === undefined || isMemoryValueConfig(memoryValueRaw);
+    const validMemoryValueConfig = memoryValueRaw === undefined || isJsonObject(memoryValueRaw);
     if (!validMemoryValueConfig) {
         log.warn(`config.json's "memoryValue" must be an object like {"enabled": true} ` +
             `(got ${JSON.stringify(memoryValueRaw)}) - using defaults.`);
     }
-    return memoryValueRaw !== undefined && isMemoryValueConfig(memoryValueRaw) ? memoryValueRaw : {};
+    return memoryValueRaw !== undefined && isJsonObject(memoryValueRaw) ? memoryValueRaw : {};
 }
 function dormantSettings(raw) {
     // Same rule as memoryValue above: a malformed value never silently
     // changes what sleep does. Anything but a real object / boolean / number
     // warns and falls back to the default, which keeps faded memories.
     const dormantRaw = raw.dormant;
-    if (dormantRaw !== undefined && !isDormantConfig(dormantRaw)) {
+    if (dormantRaw !== undefined && !isJsonObject(dormantRaw)) {
         log.warn(`config.json's "dormant" must be an object like {"enabled": false} ` +
             `(got ${JSON.stringify(dormantRaw)}) - using the default (faded memories kept dormant).`);
     }
-    const dormantOverride = dormantRaw !== undefined && isDormantConfig(dormantRaw) ? dormantRaw : {};
+    const dormantOverride = dormantRaw !== undefined && isJsonObject(dormantRaw) ? dormantRaw : {};
     // Only a real boolean counts: {"enabled": "false"} is a truthy string.
     let dormantEnabled = dormantOverride.enabled ?? DEFAULT_CONFIG.dormant.enabled;
     if (dormantEnabled !== true && dormantEnabled !== false) {
@@ -196,12 +185,12 @@ function dormantSettings(raw) {
 function churnStalenessEnabled(raw) {
     // Same "never silently wrong" rule as memoryValue/dormant above.
     const churnStalenessRaw = raw.churnStaleness;
-    const validChurnStalenessConfig = churnStalenessRaw === undefined || isChurnStalenessConfig(churnStalenessRaw);
+    const validChurnStalenessConfig = churnStalenessRaw === undefined || isJsonObject(churnStalenessRaw);
     if (!validChurnStalenessConfig) {
         log.warn(`config.json's "churnStaleness" must be an object like {"enabled": true} ` +
             `(got ${JSON.stringify(churnStalenessRaw)}) - using defaults.`);
     }
-    const enabled = churnStalenessRaw !== undefined && isChurnStalenessConfig(churnStalenessRaw)
+    const enabled = churnStalenessRaw !== undefined && isJsonObject(churnStalenessRaw)
         ? churnStalenessRaw.enabled
         : DEFAULT_CONFIG.churnStaleness.enabled;
     if (enabled !== true && enabled !== false) {
@@ -230,63 +219,95 @@ function sharedStoreFlag(raw) {
     return false;
 }
 export function loadConfig(hippoRoot) {
-    const configPath = path.join(hippoRoot, 'config.json');
-    if (!fs.existsSync(configPath))
+    // A caller that names no folder, as an add-on serving another store does, gets the defaults, never the working folder's config.json.
+    if (hippoRoot === '')
         return { ...DEFAULT_CONFIG };
+    const configPath = path.join(hippoRoot, 'config.json');
+    const key = path.resolve(configPath);
+    const stamp = fileStamp(configPath);
+    const hit = parsedConfigs.get(key);
+    if (hit !== undefined && hit.stamp === stamp)
+        return { ...hit.config };
+    const config = stamp === null ? DEFAULT_CONFIG : parseConfigFile(configPath);
+    if (parsedConfigs.size >= PARSED_CONFIGS_MAX)
+        parsedConfigs.clear();
+    parsedConfigs.set(key, { stamp, config });
+    return { ...config };
+}
+const PARSED_CONFIGS_MAX = 64;
+// Each path's parsed config with the stamp of the file it came from, so an unchanged file costs one stat and no parse.
+const parsedConfigs = new Map();
+/** A file's mtime and size, which an edit changes; null when it is missing or cannot be reached, as existsSync answers false. */
+function fileStamp(file) {
+    try {
+        const stat = fs.statSync(file, { throwIfNoEntry: false });
+        return stat === undefined ? null : `${stat.mtimeMs}:${stat.size}`;
+    }
+    catch (err) {
+        log.debug(`config: ${file} could not be reached, read as missing: ${errorMessage(err)}`);
+        return null;
+    }
+}
+function parseConfigFile(configPath) {
     try {
         const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-        const basis = raw.decayBasis;
-        const validBasis = basis === 'clock' || basis === 'session' || basis === 'adaptive';
-        const memoryValue = memoryValueOverride(raw);
-        const dormant = dormantSettings(raw);
-        const churnEnabled = churnStalenessEnabled(raw);
-        const halfLifeDays = defaultHalfLifeDays(raw);
-        return {
-            defaultHalfLifeDays: halfLifeDays,
-            defaultBudget: raw.defaultBudget ?? DEFAULT_CONFIG.defaultBudget,
-            defaultContextBudget: raw.defaultContextBudget ?? DEFAULT_CONFIG.defaultContextBudget,
-            decayBasis: validBasis ? basis : DEFAULT_CONFIG.decayBasis,
-            autoLearnOnSleep: raw.autoLearnOnSleep ?? DEFAULT_CONFIG.autoLearnOnSleep,
-            autoShareOnSleep: raw.autoShareOnSleep ?? DEFAULT_CONFIG.autoShareOnSleep,
-            autoSleep: { ...DEFAULT_CONFIG.autoSleep, ...(raw.autoSleep ?? {}) },
-            embeddings: { ...DEFAULT_CONFIG.embeddings, ...(raw.embeddings ?? {}) },
-            global: { ...DEFAULT_CONFIG.global, ...(raw.global ?? {}) },
-            gitLearnPatterns: raw.gitLearnPatterns ?? DEFAULT_CONFIG.gitLearnPatterns,
-            physics: mergePhysicsConfig(raw.physics),
-            mmr: { ...DEFAULT_CONFIG.mmr, ...(raw.mmr ?? {}) },
-            search: { ...DEFAULT_CONFIG.search, ...(raw.search ?? {}) },
-            replay: { ...DEFAULT_CONFIG.replay, ...(raw.replay ?? {}) },
-            autoTraceCapture: raw.autoTraceCapture ?? DEFAULT_CONFIG.autoTraceCapture,
-            autoTraceWindowDays: raw.autoTraceWindowDays ?? DEFAULT_CONFIG.autoTraceWindowDays,
-            pinnedInject: { ...DEFAULT_CONFIG.pinnedInject, ...(raw.pinnedInject ?? {}) },
-            contextProjectIsolation: raw.contextProjectIsolation ?? DEFAULT_CONFIG.contextProjectIsolation,
-            extraction: { ...DEFAULT_CONFIG.extraction, ...(raw.extraction ?? {}) },
-            multihop: { ...DEFAULT_CONFIG.multihop, ...(raw.multihop ?? {}) },
-            salience: { ...DEFAULT_CONFIG.salience, ...(raw.salience ?? {}) },
-            ambient: { ...DEFAULT_CONFIG.ambient, ...(raw.ambient ?? {}) },
-            memoryValue: {
-                ...DEFAULT_CONFIG.memoryValue,
-                ...memoryValue,
-            },
-            dormant,
-            churnStaleness: {
-                enabled: churnEnabled,
-            },
-            agentMemories: { tools: agentMemoryTools(raw.agentMemories?.tools) },
-            deliveryLedger: { enabled: deliveryLedgerEnabled(raw.deliveryLedger) },
-            pilot: { holdoutRateBp: pilotHoldoutRate(raw.pilot) },
-            projectIdentity: { remote: projectIdentityRemote(raw.projectIdentity) },
-            sharedStore: sharedStoreFlag(raw),
-        };
+        return configOverDefaults(raw);
     }
     catch (err) {
         if (fs.existsSync(configPath)) {
-            log.warn(`failed to parse ${configPath}: ${err instanceof Error ? err.message : err}`);
+            log.warn(`failed to parse ${configPath}: ${errorMessage(err)}`);
         }
         return { ...DEFAULT_CONFIG };
     }
 }
+function configOverDefaults(raw) {
+    const basis = raw.decayBasis;
+    const validBasis = basis === 'clock' || basis === 'session' || basis === 'adaptive';
+    const memoryValue = memoryValueOverride(raw);
+    const dormant = dormantSettings(raw);
+    const churnEnabled = churnStalenessEnabled(raw);
+    const halfLifeDays = defaultHalfLifeDays(raw);
+    return {
+        defaultHalfLifeDays: halfLifeDays,
+        defaultBudget: raw.defaultBudget ?? DEFAULT_CONFIG.defaultBudget,
+        defaultContextBudget: raw.defaultContextBudget ?? DEFAULT_CONFIG.defaultContextBudget,
+        decayBasis: validBasis ? basis : DEFAULT_CONFIG.decayBasis,
+        autoLearnOnSleep: raw.autoLearnOnSleep ?? DEFAULT_CONFIG.autoLearnOnSleep,
+        autoShareOnSleep: raw.autoShareOnSleep ?? DEFAULT_CONFIG.autoShareOnSleep,
+        autoSleep: { ...DEFAULT_CONFIG.autoSleep, ...(raw.autoSleep ?? {}) },
+        embeddings: { ...DEFAULT_CONFIG.embeddings, ...(raw.embeddings ?? {}) },
+        global: { ...DEFAULT_CONFIG.global, ...(raw.global ?? {}) },
+        gitLearnPatterns: raw.gitLearnPatterns ?? DEFAULT_CONFIG.gitLearnPatterns,
+        physics: mergePhysicsConfig(raw.physics),
+        mmr: { ...DEFAULT_CONFIG.mmr, ...(raw.mmr ?? {}) },
+        search: { ...DEFAULT_CONFIG.search, ...(raw.search ?? {}) },
+        replay: { ...DEFAULT_CONFIG.replay, ...(raw.replay ?? {}) },
+        autoTraceCapture: raw.autoTraceCapture ?? DEFAULT_CONFIG.autoTraceCapture,
+        autoTraceWindowDays: raw.autoTraceWindowDays ?? DEFAULT_CONFIG.autoTraceWindowDays,
+        pinnedInject: { ...DEFAULT_CONFIG.pinnedInject, ...(raw.pinnedInject ?? {}) },
+        contextProjectIsolation: raw.contextProjectIsolation ?? DEFAULT_CONFIG.contextProjectIsolation,
+        extraction: { ...DEFAULT_CONFIG.extraction, ...(raw.extraction ?? {}) },
+        multihop: { ...DEFAULT_CONFIG.multihop, ...(raw.multihop ?? {}) },
+        salience: { ...DEFAULT_CONFIG.salience, ...(raw.salience ?? {}) },
+        ambient: { ...DEFAULT_CONFIG.ambient, ...(raw.ambient ?? {}) },
+        memoryValue: {
+            ...DEFAULT_CONFIG.memoryValue,
+            ...memoryValue,
+        },
+        dormant,
+        churnStaleness: {
+            enabled: churnEnabled,
+        },
+        agentMemories: { tools: agentMemoryTools(raw.agentMemories?.tools) },
+        deliveryLedger: { enabled: deliveryLedgerEnabled(raw.deliveryLedger) },
+        pilot: { holdoutRateBp: pilotHoldoutRate(raw.pilot) },
+        projectIdentity: { remote: projectIdentityRemote(raw.projectIdentity) },
+        sharedStore: sharedStoreFlag(raw),
+    };
+}
 const sharedStoreRoots = new Set();
+// The stamp of each config.json last read as not shared: an unchanged file is not parsed again.
+const notSharedStamps = new Map();
 /** The folder as isGlobalStoreRoot compares it (realpath, case-folded on Windows); its helper sits behind an import cycle. */
 function sharedStoreKey(hippoRoot) {
     let real;
@@ -294,30 +315,35 @@ function sharedStoreKey(hippoRoot) {
         real = fs.realpathSync.native(hippoRoot);
     }
     catch (err) {
-        log.debug(`sharedStore: realpath fell back to resolve for ${hippoRoot}: ${err instanceof Error ? err.message : String(err)}`);
+        log.debug(`sharedStore: realpath fell back to resolve for ${hippoRoot}: ${errorMessage(err)}`);
         real = path.resolve(hippoRoot);
     }
     return process.platform === 'win32' ? real.toLowerCase() : real;
 }
 /** True when the store's config.json sets `"sharedStore": true`. Once true, a root stays true for this process,
- *  so a broken edit while a server runs cannot turn it off. Reads only this key: loadConfig has no cache. */
+ *  so a broken edit while a server runs cannot turn it off. Reads only this key, so loadConfig's warnings stay loadConfig's. */
 export function isSharedStore(hippoRoot) {
     const key = sharedStoreKey(hippoRoot);
     if (sharedStoreRoots.has(key))
         return true;
     const configPath = path.join(path.resolve(hippoRoot), 'config.json');
-    if (!fs.existsSync(configPath))
+    const stamp = fileStamp(configPath);
+    if (stamp === null || notSharedStamps.get(configPath) === stamp)
         return false;
     let raw;
     try {
         raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
     }
     catch (err) {
-        log.warn(`failed to read ${configPath}: ${err instanceof Error ? err.message : err} - sharedStore read as false.`);
+        log.warn(`failed to read ${configPath}: ${errorMessage(err)} - sharedStore read as false.`);
         return false;
     }
-    if (raw?.sharedStore !== true)
+    if (raw?.sharedStore !== true) {
+        if (notSharedStamps.size >= PARSED_CONFIGS_MAX)
+            notSharedStamps.clear();
+        notSharedStamps.set(configPath, stamp);
         return false;
+    }
     sharedStoreRoots.add(key);
     return true;
 }
@@ -328,5 +354,6 @@ export function markSharedStore(hippoRoot) {
 /** Test seam: forget every root seen as shared. */
 export function _resetSharedStoreCacheForTests() {
     sharedStoreRoots.clear();
+    notSharedStamps.clear();
 }
 //# sourceMappingURL=config.js.map

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',