hippo-memory 1.70.0 → 1.71.0

package/dist/core/ablation.d.ts

@@ -1,89 +1,6 @@
-/**
- * EVAL-ONLY lifecycle ablation switches.
- *
- * These env flags exist for controlled experiments on hippo's memory-lifecycle
- * mechanisms (the "lifecycle, ablated" paper protocol): each switch neutralizes
- * exactly ONE mechanism so its causal contribution can be measured in isolation.
- *
- * They are NOT a production configuration surface:
- *   - no config-file equivalents, deliberately (config implies support);
- *   - undocumented in user-facing help;
- *   - semantics may change with the experiment design.
- * Production behavior with all flags unset is byte-identical to before this
- * module existed.
- *
- * Flags (set to '1' or 'true'):
- *   HIPPO_ABLATE_DECAY         time-decay term := 1 in calculateStrength.
- *   HIPPO_ABLATE_RECALL_BOOST  full recall-strengthening ablation:
- *                              - markRetrieved returns entries UNMUTATED (no
- *                                clock reset / count / half-life increment);
- *                                ids stay available so `hippo outcome`
- *                                attribution keeps working in this arm;
- *                              - persisting callers (CLI recall, api context,
- *                                MCP recall/context, consolidation replay)
- *                                skip their writeEntry loops (identical-row
- *                                writes still refresh updated_at / mirrors /
- *                                DAG dirty flags);
- *                              - the retrieval-count READ boost := 1;
- *                              - decay anchors at `created` instead of
- *                                `last_retrieved` (prior-run clock resets
- *                                cannot leak in);
- *                              - physics: computeMass ignores the count, and
- *                                physicsSearch recomputes loaded masses LIVE
- *                                under ablated strength rules (persisted
- *                                masses embed recall history in their frozen
- *                                strength component);
- *                              - replay rehearsal is silenced entirely (it IS
- *                                strengthening; use config replay.count=0 to
- *                                separate replay in unflagged arms).
- *                              CAVEAT: half_life increments persisted by
- *                              prior unflagged runs are NOT reconstructed
- *                              (consolidation legitimately writes half_life
- *                              too) - ablation arms run on FRESH stores, as
- *                              the experiment protocol mandates.
- *   HIPPO_ABLATE_OUTCOME       both outcome channels := neutral
- *                              (= _SLOW + _FAST together). The slow side also
- *                              silences replay's outcome reward bias
- *                              (replayPriority). NOT gated: the opt-in
- *                              `recall --value-aware` rerank (an explicit CLI
- *                              flag that also reads outcome counts) - ablated
- *                              arms must not pass it.
- *   HIPPO_ABLATE_OUTCOME_SLOW  rewardFactor := 1 (no half-life modulation).
- *   HIPPO_ABLATE_OUTCOME_FAST  hybridSearch outcomeBoost := 1.
- *   HIPPO_ABLATE_RECENCY       search recency factor := 1 (the creation-age
- *                              multiplier 0.8 + 0.2*exp(-age/30d)); decay,
- *                              strengthening and outcomes stay live.
- *   HIPPO_EVAL_RECENCY_DAYS    a positive number replaces the 30-day scale of
- *                              that recency factor (tuning grids only). Unset,
- *                              zero, negative or junk values keep 30.
- *   HIPPO_FAKE_NOW            timestamp injected as the default `now` for
- *                              strength computation and retrieval stamping
- *                              (simulated-time protocols). MUST be the exact
- *                              Date.toISOString() form
- *                              (YYYY-MM-DDTHH:mm:ss.sssZ); validated by
- *                              round-trip, so junk, locale dates, non-UTC
- *                              offsets, and rolled-over dates (2026-02-31)
- *                              all fall back to the real clock.
- *
- * Formula notes (load-bearing for the experiments) - ablating decay has TWO
- * intrinsic co-effects, because the unified formula routes other mechanisms
- * THROUGH the decay term. Both are real properties of the architecture, not
- * implementation accidents; experiment analysis must attribute accordingly
- * (the decay-off arm is "decay + its dependents off", see prereg amendment A1):
- *   1. Read-side strengthening flattens: raw = retrievalBoost * emotionalMult
- *      >= 1, and the [0,1] clamp caps it at 1.0 - the recall boost can only
- *      offset decay, never exceed baseline. (Write-side still runs.)
- *   2. Outcome-slow goes inert: rewardFactor only acts by scaling the
- *      effective half-life INSIDE the decay exponent; with decay := 1 there
- *      is no exponent for it to modulate. Outcome-slow is decay-rate
- *      modulation BY DESIGN, so "no decay" necessarily means "no slow
- *      channel" (the fast channel in hybridSearch is unaffected).
- *
- * Env caching follows the house pattern (see getLossAversionRatio in
- * memory.ts): read once per process, with a test-only reset helper. Tests
- * that mutate these env vars MUST call _resetAblationCacheForTests() in BOTH
- * beforeEach AND afterEach.
- */
+/** EVAL-ONLY ablation switches (HIPPO_ABLATE_*, HIPPO_EVAL_RECENCY_DAYS, HIPPO_FAKE_NOW): each cuts ONE mechanism (outcome also replayPriority bias).
+ * Not a production surface. Env is read once per process; tests that mutate these vars MUST call _resetAblationCacheForTests() in beforeEach AND afterEach. See
+ * docs/ARCHITECTURE.md#srccoreablationts. */
 export declare function isDecayAblated(): boolean;
 export declare function isRecallBoostAblated(): boolean;
 export declare function isOutcomeSlowAblated(): boolean;
@@ -91,11 +8,7 @@ export declare function isOutcomeFastAblated(): boolean;
 export declare function isRecencyAblated(): boolean;
 /** HIPPO_EVAL_RECENCY_DAYS when it is a positive number, else null (callers keep their default). */
 export declare function evalRecencyScaleDays(): number | null;
-/**
- * The default `now` for lifecycle computations: HIPPO_FAKE_NOW when set and
- * parseable, else the real clock. Callers that already take an explicit `now`
- * parameter are unaffected (explicit always wins).
- */
+/** The default `now` for lifecycle computations: HIPPO_FAKE_NOW when set and parseable, else the real clock; an explicit `now` parameter always wins. */
 export declare function evalNow(): Date;
 /** Test-only. See module JSDoc: call in BOTH beforeEach AND afterEach. */
 export declare function _resetAblationCacheForTests(): void;

package/dist/core/ablation.js

@@ -1,89 +1,6 @@
-/**
- * EVAL-ONLY lifecycle ablation switches.
- *
- * These env flags exist for controlled experiments on hippo's memory-lifecycle
- * mechanisms (the "lifecycle, ablated" paper protocol): each switch neutralizes
- * exactly ONE mechanism so its causal contribution can be measured in isolation.
- *
- * They are NOT a production configuration surface:
- *   - no config-file equivalents, deliberately (config implies support);
- *   - undocumented in user-facing help;
- *   - semantics may change with the experiment design.
- * Production behavior with all flags unset is byte-identical to before this
- * module existed.
- *
- * Flags (set to '1' or 'true'):
- *   HIPPO_ABLATE_DECAY         time-decay term := 1 in calculateStrength.
- *   HIPPO_ABLATE_RECALL_BOOST  full recall-strengthening ablation:
- *                              - markRetrieved returns entries UNMUTATED (no
- *                                clock reset / count / half-life increment);
- *                                ids stay available so `hippo outcome`
- *                                attribution keeps working in this arm;
- *                              - persisting callers (CLI recall, api context,
- *                                MCP recall/context, consolidation replay)
- *                                skip their writeEntry loops (identical-row
- *                                writes still refresh updated_at / mirrors /
- *                                DAG dirty flags);
- *                              - the retrieval-count READ boost := 1;
- *                              - decay anchors at `created` instead of
- *                                `last_retrieved` (prior-run clock resets
- *                                cannot leak in);
- *                              - physics: computeMass ignores the count, and
- *                                physicsSearch recomputes loaded masses LIVE
- *                                under ablated strength rules (persisted
- *                                masses embed recall history in their frozen
- *                                strength component);
- *                              - replay rehearsal is silenced entirely (it IS
- *                                strengthening; use config replay.count=0 to
- *                                separate replay in unflagged arms).
- *                              CAVEAT: half_life increments persisted by
- *                              prior unflagged runs are NOT reconstructed
- *                              (consolidation legitimately writes half_life
- *                              too) - ablation arms run on FRESH stores, as
- *                              the experiment protocol mandates.
- *   HIPPO_ABLATE_OUTCOME       both outcome channels := neutral
- *                              (= _SLOW + _FAST together). The slow side also
- *                              silences replay's outcome reward bias
- *                              (replayPriority). NOT gated: the opt-in
- *                              `recall --value-aware` rerank (an explicit CLI
- *                              flag that also reads outcome counts) - ablated
- *                              arms must not pass it.
- *   HIPPO_ABLATE_OUTCOME_SLOW  rewardFactor := 1 (no half-life modulation).
- *   HIPPO_ABLATE_OUTCOME_FAST  hybridSearch outcomeBoost := 1.
- *   HIPPO_ABLATE_RECENCY       search recency factor := 1 (the creation-age
- *                              multiplier 0.8 + 0.2*exp(-age/30d)); decay,
- *                              strengthening and outcomes stay live.
- *   HIPPO_EVAL_RECENCY_DAYS    a positive number replaces the 30-day scale of
- *                              that recency factor (tuning grids only). Unset,
- *                              zero, negative or junk values keep 30.
- *   HIPPO_FAKE_NOW            timestamp injected as the default `now` for
- *                              strength computation and retrieval stamping
- *                              (simulated-time protocols). MUST be the exact
- *                              Date.toISOString() form
- *                              (YYYY-MM-DDTHH:mm:ss.sssZ); validated by
- *                              round-trip, so junk, locale dates, non-UTC
- *                              offsets, and rolled-over dates (2026-02-31)
- *                              all fall back to the real clock.
- *
- * Formula notes (load-bearing for the experiments) - ablating decay has TWO
- * intrinsic co-effects, because the unified formula routes other mechanisms
- * THROUGH the decay term. Both are real properties of the architecture, not
- * implementation accidents; experiment analysis must attribute accordingly
- * (the decay-off arm is "decay + its dependents off", see prereg amendment A1):
- *   1. Read-side strengthening flattens: raw = retrievalBoost * emotionalMult
- *      >= 1, and the [0,1] clamp caps it at 1.0 - the recall boost can only
- *      offset decay, never exceed baseline. (Write-side still runs.)
- *   2. Outcome-slow goes inert: rewardFactor only acts by scaling the
- *      effective half-life INSIDE the decay exponent; with decay := 1 there
- *      is no exponent for it to modulate. Outcome-slow is decay-rate
- *      modulation BY DESIGN, so "no decay" necessarily means "no slow
- *      channel" (the fast channel in hybridSearch is unaffected).
- *
- * Env caching follows the house pattern (see getLossAversionRatio in
- * memory.ts): read once per process, with a test-only reset helper. Tests
- * that mutate these env vars MUST call _resetAblationCacheForTests() in BOTH
- * beforeEach AND afterEach.
- */
+/** EVAL-ONLY ablation switches (HIPPO_ABLATE_*, HIPPO_EVAL_RECENCY_DAYS, HIPPO_FAKE_NOW): each cuts ONE mechanism (outcome also replayPriority bias).
+ * Not a production surface. Env is read once per process; tests that mutate these vars MUST call _resetAblationCacheForTests() in beforeEach AND afterEach. See
+ * docs/ARCHITECTURE.md#srccoreablationts. */
 import { envAblateDecay, envAblateOutcome, envAblateOutcomeFast, envAblateOutcomeSlow, envAblateRecallBoost, envAblateRecency, envEvalRecencyDays, envFakeNowMs, } from '../util/env.js';
 let _cache;
 function readFlags() {
@@ -120,11 +37,7 @@ export function isRecencyAblated() {
 export function evalRecencyScaleDays() {
     return readFlags().recencyDays;
 }
-/**
- * The default `now` for lifecycle computations: HIPPO_FAKE_NOW when set and
- * parseable, else the real clock. Callers that already take an explicit `now`
- * parameter are unaffected (explicit always wins).
- */
+/** The default `now` for lifecycle computations: HIPPO_FAKE_NOW when set and parseable, else the real clock; an explicit `now` parameter always wins. */
 export function evalNow() {
     const ms = readFlags().fakeNowMs;
     return ms === null ? new Date() : new Date(ms);

package/dist/core/ambient.d.ts

@@ -1,11 +1,4 @@
-/**
- * Ambient state vector — a compact representation of the agent's memory
- * landscape, computed in O(N) from the current corpus.
- *
- * Inspired by the biological ambient neural state: a continuous background
- * representation that tells the agent "where it is" in knowledge-space
- * without retrieving specific memories.
- */
+/** Ambient state vector: a compact O(N) summary of the corpus telling the agent "where it is" in knowledge-space without retrieving specific memories. */
 import type { MemoryEntry } from './memory.js';
 export interface AmbientState {
     tagEntropy: number;

package/dist/core/ambient.js

@@ -1,11 +1,4 @@
-/**
- * Ambient state vector — a compact representation of the agent's memory
- * landscape, computed in O(N) from the current corpus.
- *
- * Inspired by the biological ambient neural state: a continuous background
- * representation that tells the agent "where it is" in knowledge-space
- * without retrieving specific memories.
- */
+/** Ambient state vector: a compact O(N) summary of the corpus telling the agent "where it is" in knowledge-space without retrieving specific memories. */
 import { evalNow } from './ablation.js';
 import { Layer } from './memory.js';
 import { calculateStrength } from './memory.js';

package/dist/core/capture-contract.d.ts

@@ -51,12 +51,14 @@ export declare function isStringValue<T>(value: T): value is T & string;
 export declare function isObjectLike<T>(value: T): value is T & object;
 /** The hook runtimes a `--runtime` flag names; absent means Claude Code. */
 export type HookRuntime = 'claude-code' | 'copilot';
-/** Reads a Claude Code PreCompact 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. */
+/** Reads a Claude Code PreCompact 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 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. */
+/** 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/core/capture-contract.js

@@ -8,7 +8,8 @@ export function isStringValue(value) {
 export function isObjectLike(value) {
     return value !== null && value instanceof Object;
 }
-/** Reads a Claude Code PreCompact 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. */
+/** Reads a Claude Code PreCompact 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 readClaudeCodePreCompact(stdinText, timedOut, runtime = 'claude-code') {
     const empty = !stdinText || stdinText.trim() === '';
     if (timedOut && empty) {
@@ -112,7 +113,8 @@ export function readClaudeCodePostCompact(stdinText, timedOut) {
         },
     };
 }
-/** 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. */
+/** 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) {

package/dist/core/card.d.ts

@@ -2,7 +2,8 @@
 export type CardStatus = 'backlog' | 'ready' | 'running' | 'blocked' | 'review' | 'done' | 'shelved';
 /** Narrows a raw string, such as a CLI flag value, to a CardStatus. */
 export declare function isCardStatus(v: string): v is CardStatus;
-/** A card row; leaseUntil and heartbeatAt are null unless the card is running, and a card claimed under 1.40.0 runs with both null until a heartbeat sets them. */
+/** A card row; leaseUntil and heartbeatAt are null unless the card is running, and
+ * a card claimed under 1.40.0 runs with both null until a heartbeat sets them. */
 export interface Card {
     id: string;
     title: string;
@@ -44,4 +45,6 @@ export type CardTransitions = {
 export declare const CARD_TRANSITIONS: CardTransitions;
 /** How long a claim or a heartbeat keeps a running card's lease before reclaimExpiredCards may return it to ready. */
 export declare const CARD_LEASE_MS: number;
+/** Throws on any move CARD_TRANSITIONS does not allow, before a status write touches the row. */
+export declare function assertCardTransition(from: readonly CardStatus[], to: CardStatus): void;
 //# sourceMappingURL=card.d.ts.map

package/dist/core/card.js

@@ -16,4 +16,12 @@ export const CARD_TRANSITIONS = {
 // SHORTCUT: one fixed lease for every claim; add a per-claim lease when the W3 dispatcher heartbeats on a timer.
 /** How long a claim or a heartbeat keeps a running card's lease before reclaimExpiredCards may return it to ready. */
 export const CARD_LEASE_MS = 4 * 60 * 60 * 1000;
+/** Throws on any move CARD_TRANSITIONS does not allow, before a status write touches the row. */
+export function assertCardTransition(from, to) {
+    for (const status of from) {
+        if (!CARD_TRANSITIONS[status].includes(to)) {
+            throw new Error(`illegal card transition: ${status} -> ${to}`);
+        }
+    }
+}
 //# sourceMappingURL=card.js.map

package/dist/core/compare.d.ts

@@ -1,21 +1,8 @@
-/**
- * Deterministic tie-break comparators for recall ranking.
- *
- * A true LEAF module: imports NOTHING from any sort-site module (search.ts,
- * physics.ts, api.ts, cli.ts, shared.ts, goals.ts, graph-recall.ts,
- * multihop.ts, rerankers/*). Every comparator here takes a structural param
- * type instead of an imported one, on purpose — a type-only import back to
- * search.ts would still create the search.ts <-> physics.ts ESM import
- * cycle this module exists to avoid.
- *
- * Mirrors the deliberate-determinism comment style already established in
- * graph-stream.ts:88, :165-168, :233-236 — a sort with a documented,
- * reproducible tiebreak instead of leaving ties to array/scan order.
- */
-/** Minimal shape needed to break a tie deterministically across fresh
- *  ingests of the same content into different stores. The metadata keys are
- *  optional so existing `{ content, id }` callers (tests, benchmarks) still fit;
- *  a full MemoryEntry satisfies it structurally and gets the metadata order. */
+/** Deterministic tie-break comparators for recall ranking. A true LEAF module: it imports from no sort-site module (search, physics, api, cli, goals,
+ * graph-recall, multihop, rerankers), taking structural param types instead, because even a type-only import back would recreate the search <-> physics ESM
+ * cycle this module exists to avoid. */
+/** Minimal shape for a deterministic tie-break across fresh ingests into different stores;
+ *  the metadata keys are optional so `{ content, id }` callers still fit. */
 export interface EntryIdentity {
     content: string;
     id: string;
@@ -23,30 +10,8 @@ export interface EntryIdentity {
     tags?: readonly string[];
     source?: string;
 }
-/**
- * content asc -> layer rank asc -> distinct tag count desc -> sorted tags asc
- * -> source asc -> id asc (all string compares are UTF-16 code-unit order).
- *
- * `content` is the cross-ingest-stable key: identical text ingested into two
- * independently-created stores (different directory name, different insert
- * order of everything else on disk) sorts identically. The metadata keys make
- * byte-identical twins order by what they carry instead of by `id`
- * (`crypto.randomUUID()`), which is per-instance random and would make the
- * dedupe survivor arbitrary. `id` stays the terminal key so the order is
- * total within one store.
- *
- * Layer rank puts semantic first: semantic rows are consolidation output, so
- * keeping that copy preserves the promotion instead of demoting the memory.
- * Unknown or missing layers rank last and then compare as raw strings.
- * Tags prefer the copy with more distinct labels (fewer labels are lost on
- * dedupe); source is an arbitrary but stable key.
- *
- * Plain `<`/`>`, NOT `localeCompare`: `localeCompare` is locale- and
- * ICU-version-dependent (a determinism leak in its own right) and needlessly
- * slow for a tiebreak that only needs a total order. The metadata keys are
- * only computed on a content tie, which is rare, so the per-compare Set/sort
- * cost never lands on the hot path.
- */
+/** Order: content, layer rank (semantic first, keeping the promotion), tag count desc, sorted tags, source, id; plain `<`/`>`, never `localeCompare`.
+ * `content` is the cross-ingest-stable key; `id` is random per instance, so it is only the terminal key. Metadata keys are computed only on a content tie. */
 export declare function compareEntryIdentity(a: EntryIdentity, b: EntryIdentity): number;
 /** Minimal shape for score-primary sort sites (SearchResult and friends
  *  that carry `{ score, entry: { content, id } }`). */
@@ -54,34 +19,13 @@ export interface ScoredEntryLike {
     score: number;
     entry: EntryIdentity;
 }
-/**
- * score descending -> `compareEntryIdentity`. The shared ordering rule for
- * every score-primary recall sort site (search.ts, shared.ts, goals.ts,
- * api.ts, cli.ts, graph-recall.ts, multihop.ts, rerankers/cross-encoder.ts).
- * Sites delegate wholesale to this (via a thin arrow where the element
- * shape's score field is named something other than `score`, e.g.
- * `rerankScore`) rather than reimplementing `b.score - a.score` locally, so
- * the tiebreak can't silently drift between call sites.
- */
+/** score descending, then `compareEntryIdentity`: the shared ordering for every score-primary recall sort site, which delegate here (via an arrow when the
+ * score field is not named `score`) so the tiebreak cannot 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.
- *
- * `ScoredPhysicsResult` (physics.ts) carries `{ memoryId, baseScore,
- * clusterAmplification, finalScore }` -- NO `entry`/`content` in scope at
- * that layer, so `compareEntryIdentity` cannot apply directly. With only the
- * default memoryId key this is PER-INSTANCE-ONLY determinism; callers that need
- * CROSS-INGEST stability supply `tieKeyOf` mapping the result to its memory
- * CONTENT, because the baseScore tie order selects the cluster_top_k
- * amplification set, which MUTATES scores before the content-aware merge sort.
- *
- * A factory (not a fixed-field comparator) because physics.ts re-sorts the
- * same result array by two different score fields in sequence (`baseScore`
- * for top-K selection, then `finalScore` after cluster amplification) — one
- * shared tiebreak rule, parameterised by which field is primary this pass.
- */
+/** Score-desc then tie-key comparator for the physics layer (no `entry`/`content` in scope): the default memoryId key is per-instance determinism only.
+ * Cross-ingest stability needs `tieKeyOf` (content), since the baseScore tie order picks the cluster_top_k set. A factory, as two fields sort in turn. */
 export declare function comparePhysicsResultsBy<T extends {
     memoryId: string;
 }>(scoreOf: (r: T) => number, tieKeyOf?: (r: T) => string): (a: T, b: T) => number;

package/dist/core/compare.js

@@ -1,41 +1,8 @@
-/**
- * Deterministic tie-break comparators for recall ranking.
- *
- * A true LEAF module: imports NOTHING from any sort-site module (search.ts,
- * physics.ts, api.ts, cli.ts, shared.ts, goals.ts, graph-recall.ts,
- * multihop.ts, rerankers/*). Every comparator here takes a structural param
- * type instead of an imported one, on purpose — a type-only import back to
- * search.ts would still create the search.ts <-> physics.ts ESM import
- * cycle this module exists to avoid.
- *
- * Mirrors the deliberate-determinism comment style already established in
- * graph-stream.ts:88, :165-168, :233-236 — a sort with a documented,
- * reproducible tiebreak instead of leaving ties to array/scan order.
- */
-/**
- * content asc -> layer rank asc -> distinct tag count desc -> sorted tags asc
- * -> source asc -> id asc (all string compares are UTF-16 code-unit order).
- *
- * `content` is the cross-ingest-stable key: identical text ingested into two
- * independently-created stores (different directory name, different insert
- * order of everything else on disk) sorts identically. The metadata keys make
- * byte-identical twins order by what they carry instead of by `id`
- * (`crypto.randomUUID()`), which is per-instance random and would make the
- * dedupe survivor arbitrary. `id` stays the terminal key so the order is
- * total within one store.
- *
- * Layer rank puts semantic first: semantic rows are consolidation output, so
- * keeping that copy preserves the promotion instead of demoting the memory.
- * Unknown or missing layers rank last and then compare as raw strings.
- * Tags prefer the copy with more distinct labels (fewer labels are lost on
- * dedupe); source is an arbitrary but stable key.
- *
- * Plain `<`/`>`, NOT `localeCompare`: `localeCompare` is locale- and
- * ICU-version-dependent (a determinism leak in its own right) and needlessly
- * slow for a tiebreak that only needs a total order. The metadata keys are
- * only computed on a content tie, which is rare, so the per-compare Set/sort
- * cost never lands on the hot path.
- */
+/** Deterministic tie-break comparators for recall ranking. A true LEAF module: it imports from no sort-site module (search, physics, api, cli, goals,
+ * graph-recall, multihop, rerankers), taking structural param types instead, because even a type-only import back would recreate the search <-> physics ESM
+ * cycle this module exists to avoid. */
+/** Order: content, layer rank (semantic first, keeping the promotion), tag count desc, sorted tags, source, id; plain `<`/`>`, never `localeCompare`.
+ * `content` is the cross-ingest-stable key; `id` is random per instance, so it is only the terminal key. Metadata keys are computed only on a content tie. */
 export function compareEntryIdentity(a, b) {
     return (compareStrings(a.content, b.content) ||
         layerRank(a.layer) - layerRank(b.layer) ||
@@ -69,15 +36,8 @@ function compareTags(a, b) {
     }
     return 0;
 }
-/**
- * score descending -> `compareEntryIdentity`. The shared ordering rule for
- * every score-primary recall sort site (search.ts, shared.ts, goals.ts,
- * api.ts, cli.ts, graph-recall.ts, multihop.ts, rerankers/cross-encoder.ts).
- * Sites delegate wholesale to this (via a thin arrow where the element
- * shape's score field is named something other than `score`, e.g.
- * `rerankScore`) rather than reimplementing `b.score - a.score` locally, so
- * the tiebreak can't silently drift between call sites.
- */
+/** score descending, then `compareEntryIdentity`: the shared ordering for every score-primary recall sort site, which delegate here (via an arrow when the
+ * score field is not named `score`) so the tiebreak cannot drift between call sites. */
 export function compareScoredResults(a, b) {
     return compareScoresDesc(a.score, b.score) || compareEntryIdentity(a.entry, b.entry);
 }
@@ -89,22 +49,8 @@ export function compareScoresDesc(a, b) {
         return 1;
     return Number(Number.isNaN(a)) - Number(Number.isNaN(b));
 }
-/**
- * Build a score-desc -> tie-key comparator for the physics layer.
- *
- * `ScoredPhysicsResult` (physics.ts) carries `{ memoryId, baseScore,
- * clusterAmplification, finalScore }` -- NO `entry`/`content` in scope at
- * that layer, so `compareEntryIdentity` cannot apply directly. With only the
- * default memoryId key this is PER-INSTANCE-ONLY determinism; callers that need
- * CROSS-INGEST stability supply `tieKeyOf` mapping the result to its memory
- * CONTENT, because the baseScore tie order selects the cluster_top_k
- * amplification set, which MUTATES scores before the content-aware merge sort.
- *
- * A factory (not a fixed-field comparator) because physics.ts re-sorts the
- * same result array by two different score fields in sequence (`baseScore`
- * for top-K selection, then `finalScore` after cluster amplification) — one
- * shared tiebreak rule, parameterised by which field is primary this pass.
- */
+/** Score-desc then tie-key comparator for the physics layer (no `entry`/`content` in scope): the default memoryId key is per-instance determinism only.
+ * Cross-ingest stability needs `tieKeyOf` (content), since the baseScore tie order picks the cluster_top_k set. A factory, as two fields sort in turn. */
 export function comparePhysicsResultsBy(scoreOf, tieKeyOf) {
     return (a, b) => {
         const d = compareScoresDesc(scoreOf(a), scoreOf(b));

package/dist/core/config.d.ts

@@ -19,10 +19,8 @@ export interface HippoConfig {
         enabled: boolean | 'auto';
         model: string;
         hybridWeight: number;
-        /** 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/store/embeddings/provider.ts. */
+        /** Embedding backend: 'local' (default) = zero-dependency transformers.js; 'openai' | 'voyage' | 'cohere' = opt-in API embedder needing the provider's
+         *  API key in env (OPENAI_API_KEY / VOYAGE_API_KEY / COHERE_API_KEY). 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. */
@@ -57,18 +55,15 @@ export interface HippoConfig {
     autoTraceCapture: boolean;
     /** Only promote sessions whose session_complete event is within N days. */
     autoTraceWindowDays: number;
-    /** Mid-session pinned-rule re-injection via the Claude Code UserPromptSubmit
-     *  hook. When enabled, pinned memories are re-injected each turn within the
-     *  given token budget. */
+    /** Mid-session pinned-rule re-injection through the UserPromptSubmit hook: pinned memories are re-injected each turn within the token budget. */
     pinnedInject: {
         enabled: boolean;
         budget: number;
         /** Skip a block identical to the one already injected this session
          *  Default true. Needs a session id from the hook payload. */
         skipUnchanged: boolean;
-        /** Resend an unchanged block after this many consecutive skips, so long
-         *  sessions still see pinned rules near the latest turn. Default 10; 0
-         *  never resends an unchanged block. */
+        /** Resend an unchanged block after this many consecutive skips, so long sessions still see pinned rules near the latest turn (default 10; 0 never
+         * resends). */
         refreshTurns: number;
         /** Gate the hook's backfill on the prompt's own content instead of the five
          *  newest memories. Default true: the same overlap for fewer tokens. */
@@ -84,13 +79,8 @@ export interface HippoConfig {
         /** FTS candidate pool size per store before gating. Default 100. */
         promptRecallCandidates: number;
     };
-    /** Memory scope isolation: when true (default), ambient context
-     *  (`hippo context`, the UserPromptSubmit hook, /v1/context, MCP
-     *  hippo_context) excludes memories owned by OTHER projects; explicit
-     *  recall is unaffected. Set false to disable the ORIGIN PARTITION only -
-     *  the secret veto is unconditional for ambient surfaces and no config or
-     *  flag re-includes secret-flagged rows (explicit recall still returns
-     *  them). */
+    /** Memory scope isolation (default true): ambient context (`hippo context`, the hook, /v1/context, MCP hippo_context) excludes OTHER projects' memories;
+     *  explicit recall is unaffected. False disables the ORIGIN PARTITION only: the secret veto is unconditional, and no flag re-includes secret-flagged rows. */
     contextProjectIsolation: boolean;
     extraction: {
         enabled: boolean | 'auto';
@@ -114,13 +104,8 @@ export interface HippoConfig {
     memoryValue: {
         enabled: boolean;
     };
-    /** 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
-     *  back and `hippo dormant forget <id>` deletes it for good. A faded memory
-     *  the secret detector flags is always deleted, never kept dormant.
-     *  `{"enabled": false}` restores the old delete-on-fade behaviour. */
+    /** Dormant memories (src/store/dormant.ts), on by default: the sleep decay pass moves a memory that faded below the threshold there instead of deleting it
+     *  (`hippo dormant restore|forget <id>`); a faded memory the secret detector flags is always deleted. `{"enabled": false}` restores delete-on-fade. */
     dormant: {
         enabled: boolean;
         /** Days a dormant memory is kept before sleep deletes it for good.
@@ -155,6 +140,7 @@ export interface HippoConfig {
      *  and a context read must name the caller's project. Default false. Read it through isSharedStore. */
     sharedStore: boolean;
 }
+export declare const DEFAULT_CONFIG: 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, so loadConfig's warnings stay loadConfig's. */

package/dist/core/config.js

@@ -8,7 +8,7 @@ import { DEFAULT_HALF_LIFE_DAYS } from './memory.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 = {
+export const DEFAULT_CONFIG = {
     defaultHalfLifeDays: DEFAULT_HALF_LIFE_DAYS,
     defaultBudget: DEFAULT_RECALL_BUDGET,
     defaultContextBudget: 3000,
@@ -158,8 +158,7 @@ function memoryValueOverride(raw) {
     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
+    // 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 && !isJsonObject(dormantRaw)) {
@@ -274,22 +273,22 @@ function configOverDefaults(raw) {
         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 ?? {}) },
+        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 ?? {}) },
+        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 ?? {}) },
+        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 ?? {}) },
+        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,