hippo-memory 1.70.0 → 1.72.0

package/dist/core/ambient.js

@@ -1,16 +1,29 @@
-/**
- * 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.
- */
-import { evalNow } from './ablation.js';
+/** 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, strengthAblation } from './ablation.js';
 import { Layer } from './memory.js';
 import { calculateStrength } from './memory.js';
 import { DAY_MS } from '../util/time.js';
 const STATE_DECIMALS = 3;
+// Cut points renderAmbientSummary uses to turn the state vector into words.
+const SUMMARY_THRESHOLD = {
+    freshHigh: 0.5,
+    freshLow: 0.1,
+    skewHigh: 0.3,
+    skewLow: -0.3,
+    consolidatedHigh: 0.4,
+    consolidatedLow: 0.1,
+    extractionHigh: 0.5,
+    conflictShown: 0.1,
+    dagDepthShown: 2,
+    strengthLow: 0.3,
+    strengthHigh: 0.7,
+    entropyHigh: 0.8,
+    entropyLow: 0.3,
+};
+/** A memory is fresh when created within this window. */
+export const AMBIENT_FRESH_WINDOW_MS = 7 * DAY_MS;
+/** A memory counts as high schema fit strictly above this. */
+export const HIGH_SCHEMA_FIT_ABOVE = 0.7;
 /** The tallies of two disjoint row sets taken together. */
 export function addAmbientTallies(a, b) {
     const tagCounts = new Map(a.tagCounts);
@@ -38,7 +51,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 * DAY_MS;
+    const freshAfter = currentTime.getTime() - AMBIENT_FRESH_WINDOW_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(),
@@ -48,14 +61,14 @@ export function tallyAmbientEntries(entries, now) {
             continue;
         for (const tag of entry.tags)
             t.tagCounts.set(tag, (t.tagCounts.get(tag) ?? 0) + 1);
-        t.strengthSum += calculateStrength(entry, currentTime);
-        if (new Date(entry.created).getTime() > sevenDaysAgo)
+        t.strengthSum += calculateStrength(entry, currentTime, { ablation: strengthAblation() });
+        if (new Date(entry.created).getTime() > freshAfter)
             t.fresh++;
         if (entry.emotional_valence === 'negative' || entry.emotional_valence === 'critical')
             t.negative++;
         if (isErrorTagged(entry.tags))
             t.errors++;
-        if (entry.schema_fit > 0.7)
+        if (entry.schema_fit > HIGH_SCHEMA_FIT_ABOVE)
             t.highSchemaFit++;
         if (entry.layer === Layer.Semantic)
             t.semantic++;
@@ -123,33 +136,34 @@ function shannonEntropy(counts, total) {
 export function renderAmbientSummary(state) {
     if (state.totalMemories === 0)
         return 'Memory state: empty store, no memories yet.';
+    const T = SUMMARY_THRESHOLD;
     const parts = [];
     parts.push(`${state.totalMemories} memories`);
-    if (state.recencyFreshness > 0.5)
+    if (state.recencyFreshness > T.freshHigh)
         parts.push('mostly fresh (<7d)');
-    else if (state.recencyFreshness < 0.1)
+    else if (state.recencyFreshness < T.freshLow)
         parts.push('mostly aged');
-    if (state.emotionalSkew > 0.3)
+    if (state.emotionalSkew > T.skewHigh)
         parts.push('error-focused');
-    else if (state.emotionalSkew < -0.3)
+    else if (state.emotionalSkew < T.skewLow)
         parts.push('steady operation');
-    if (state.consolidationRatio > 0.4)
+    if (state.consolidationRatio > T.consolidatedHigh)
         parts.push('well-consolidated');
-    else if (state.consolidationRatio < 0.1)
+    else if (state.consolidationRatio < T.consolidatedLow)
         parts.push('mostly episodic');
-    if (state.extractionCoverage > 0.5)
+    if (state.extractionCoverage > T.extractionHigh)
         parts.push('high extraction coverage');
-    if (state.conflictIntensity > 0.1)
+    if (state.conflictIntensity > T.conflictShown)
         parts.push(`${(state.conflictIntensity * 100).toFixed(0)}% conflict rate`);
-    if (state.dagDepth >= 2)
+    if (state.dagDepth >= T.dagDepthShown)
         parts.push(`DAG depth ${state.dagDepth}`);
-    if (state.avgStrength < 0.3)
+    if (state.avgStrength < T.strengthLow)
         parts.push('low avg strength (aging corpus)');
-    else if (state.avgStrength > 0.7)
+    else if (state.avgStrength > T.strengthHigh)
         parts.push('high avg strength');
-    if (state.tagEntropy > 0.8)
+    if (state.tagEntropy > T.entropyHigh)
         parts.push('diverse topics');
-    else if (state.tagEntropy < 0.3)
+    else if (state.tagEntropy < T.entropyLow)
         parts.push('narrow focus');
     return `Memory state: ${parts.join(', ')}.`;
 }

package/dist/core/api-errors.d.ts

@@ -24,4 +24,20 @@ export declare class ConflictError extends ApiError {
     readonly status = 409;
     constructor(message: string);
 }
+/** Thrown by the write-path guard (checkRejectionGuard, via upsertEntryRow) when a write would introduce a tombstoned value; carries what the
+ * transaction-owner catch blocks (writeEntry, api.supersede) need to write the post-rollback `reject_refusal` audit row via `auditRejectionRefusal`. */
+export declare class RejectedValueError extends BadRequestError {
+    readonly digest: string;
+    readonly tenantId: string;
+    readonly entryId: string;
+    readonly reason: string | null;
+    readonly rejectedAt: string;
+    constructor(opts: {
+        digest: string;
+        tenantId: string;
+        entryId: string;
+        reason: string | null;
+        rejectedAt: string;
+    });
+}
 //# sourceMappingURL=api-errors.d.ts.map

package/dist/core/api-errors.js

@@ -1,4 +1,5 @@
 /** Errors whose HTTP status is part of the API contract; the server maps by class, so message text can change freely. */
+import { DIGEST_DISPLAY_CHARS } from '../util/token-text.js';
 /** Base class: an error the caller caused, carrying the status the HTTP layer answers with. */
 export class ApiError extends Error {
 }
@@ -34,4 +35,23 @@ export class ConflictError extends ApiError {
         this.name = 'ConflictError';
     }
 }
+/** Thrown by the write-path guard (checkRejectionGuard, via upsertEntryRow) when a write would introduce a tombstoned value; carries what the
+ * transaction-owner catch blocks (writeEntry, api.supersede) need to write the post-rollback `reject_refusal` audit row via `auditRejectionRefusal`. */
+export class RejectedValueError extends BadRequestError {
+    digest;
+    tenantId;
+    entryId;
+    reason;
+    rejectedAt;
+    constructor(opts) {
+        super(`Memory value refused: matches a rejected value (digest ${opts.digest.slice(0, DIGEST_DISPLAY_CHARS)}..., ` +
+            `reason: ${opts.reason ?? 'none given'}). Run "hippo unreject" to allow it again.`);
+        this.name = 'RejectedValueError';
+        this.digest = opts.digest;
+        this.tenantId = opts.tenantId;
+        this.entryId = opts.entryId;
+        this.reason = opts.reason;
+        this.rejectedAt = opts.rejectedAt;
+    }
+}
 //# sourceMappingURL=api-errors.js.map

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

@@ -1,3 +1,5 @@
+// Work-queue card types: a claimable unit of work, N candidates claim one row, first wins.
+import { HOUR_MS } from '../util/time.js';
 const CARD_STATUSES = ['backlog', 'ready', 'running', 'blocked', 'review', 'done', 'shelved'];
 /** Narrows a raw string, such as a CLI flag value, to a CardStatus. */
 export function isCardStatus(v) {
@@ -15,5 +17,13 @@ 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;
+export const CARD_LEASE_MS = 4 * HOUR_MS;
+/** 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/compaction-timing.d.ts

@@ -0,0 +1,7 @@
+/** PostCompact has 10 s in all (PreCompact 30 s), so a locked store must be given up on early. */
+export declare const COMPACTION_DB_WAIT_MS = 2000;
+/** Long enough that a live hook has finished with its own record. */
+export declare const REPLAY_AFTER_MS: number;
+/** Claude Code deletes transcripts after 30 days, so an older gap can never be filled. */
+export declare const TRANSCRIPT_FILL_WINDOW_MS: number;
+//# sourceMappingURL=compaction-timing.d.ts.map

package/dist/core/compaction-timing.js

@@ -0,0 +1,9 @@
+// Waits and windows shared by the compaction record's SQL (src/store) and the hooks and CLI that schedule it.
+import { DAY_MS, MINUTE_MS } from '../util/time.js';
+/** PostCompact has 10 s in all (PreCompact 30 s), so a locked store must be given up on early. */
+export const COMPACTION_DB_WAIT_MS = 2000;
+/** Long enough that a live hook has finished with its own record. */
+export const REPLAY_AFTER_MS = 10 * MINUTE_MS;
+/** Claude Code deletes transcripts after 30 days, so an older gap can never be filled. */
+export const TRANSCRIPT_FILL_WINDOW_MS = 30 * DAY_MS;
+//# sourceMappingURL=compaction-timing.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/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

@@ -6,9 +6,9 @@ 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 { errorMessage, log } from '../util/log.js';
+import { errorCode, 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)) {
@@ -244,7 +243,12 @@ function fileStamp(file) {
         return stat === undefined ? null : `${stat.mtimeMs}:${stat.size}`;
     }
     catch (err) {
-        log.debug(`config: ${file} could not be reached, read as missing: ${errorMessage(err)}`);
+        const code = errorCode(err);
+        const message = `config: ${file} could not be reached, read as missing: ${errorMessage(err)}`;
+        if (code === 'EACCES' || code === 'EPERM')
+            log.warnThenDebug(`config-unreachable:${file}:${code}`, message, { path: file, code });
+        else
+            log.debug(message);
         return null;
     }
 }
@@ -274,22 +278,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,

package/dist/core/cosine.d.ts

@@ -0,0 +1,3 @@
+/** Cosine over any indexable vectors (a Float32 view scores as its number[] copy); 0 for empty, mismatched or zero-norm input. */
+export declare function cosineOf(a: ArrayLike<number>, b: ArrayLike<number>): number;
+//# sourceMappingURL=cosine.d.ts.map

package/dist/core/cosine.js

@@ -0,0 +1,19 @@
+/** Cosine over any indexable vectors (a Float32 view scores as its number[] copy); 0 for empty, mismatched or zero-norm input. */
+export function cosineOf(a, b) {
+    if (a.length === 0 || b.length === 0 || a.length !== b.length)
+        return 0;
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    if (denom < 1e-10)
+        return 0;
+    // Clamp to [-1, 1] to handle floating point drift
+    return Math.min(1, Math.max(-1, dot / denom));
+}
+//# sourceMappingURL=cosine.js.map