hippo-memory 1.72.0 → 2.1.0

package/dist/core/ablation.js

@@ -1,9 +1,16 @@
-/** 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
+/**
+ * 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';
 /** Production scoring: nothing ablated. Core falls back to this, so it never reads the environment. */
-export const NO_STRENGTH_ABLATION = Object.freeze({ decay: false, recallBoost: false, outcomeSlow: false });
+export const NO_STRENGTH_ABLATION = Object.freeze({
+    decay: false,
+    recallBoost: false,
+    outcomeSlow: false,
+});
 let _cache;
 let _strengthCache;
 function readFlags() {
@@ -48,7 +55,10 @@ 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; an explicit `now` parameter 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/active-scope.d.ts

@@ -1,4 +1,6 @@
-/** Detect the current operational scope from env (HIPPO_SCOPE > GSTACK_SKILL > OPENCLAW_SKILL); returns the name without prefix, or null.
+/**
+ * Detect the current operational scope from env (HIPPO_SCOPE > GSTACK_SKILL > OPENCLAW_SKILL); returns the name without
+ * prefix, or null.
  *  Pure env reads, no I/O, so it is safe on hot paths such as the UserPromptSubmit hook. */
 export declare function detectScope(): string | null;
 /** Compute scope match between a memory's scope tags and the active scope.

package/dist/core/active-scope.js

@@ -1,5 +1,7 @@
 import { envGstackSkill, envOpenclawSkill, envScope } from '../util/env.js';
-/** Detect the current operational scope from env (HIPPO_SCOPE > GSTACK_SKILL > OPENCLAW_SKILL); returns the name without prefix, or null.
+/**
+ * Detect the current operational scope from env (HIPPO_SCOPE > GSTACK_SKILL > OPENCLAW_SKILL); returns the name without
+ * prefix, or null.
  *  Pure env reads, no I/O, so it is safe on hot paths such as the UserPromptSubmit hook. */
 export function detectScope() {
     const explicit = envScope();

package/dist/core/agent-memory-tools.d.ts

@@ -26,6 +26,8 @@ export declare const AGENT_MEMORY_TOOLS: readonly [{
 export type AgentMemoryTool = (typeof AGENT_MEMORY_TOOLS)[number];
 export type ToolId = AgentMemoryTool['id'];
 export declare const AGENT_MEMORY_SOURCE_PREFIX = "agent-memory:";
+/** The actor on every row and audit event the agent-memories import writes. */
+export declare const SYNC_ACTOR = "agent-memories";
 /** Every imported row of a tool has a source starting with this. */
 export declare function toolSourcePrefix(id: ToolId): string;
 export declare const AGENT_MEMORY_TAGS: readonly string[];

package/dist/core/agent-memory-tools.js

@@ -8,6 +8,8 @@ export const AGENT_MEMORY_TOOLS = [
     { id: 'qwen-code', tag: 'qwen-code-memory', label: 'Qwen Code' },
 ];
 export const AGENT_MEMORY_SOURCE_PREFIX = 'agent-memory:';
+/** The actor on every row and audit event the agent-memories import writes. */
+export const SYNC_ACTOR = 'agent-memories';
 /** Every imported row of a tool has a source starting with this. */
 export function toolSourcePrefix(id) {
     return `${AGENT_MEMORY_SOURCE_PREFIX}${id}:`;

package/dist/core/ambient.d.ts

@@ -1,4 +1,7 @@
-/** Ambient state vector: a compact O(N) summary of the corpus telling 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;
@@ -15,8 +18,6 @@ export interface AmbientState {
 }
 /** A memory is fresh when created within this window. */
 export declare const AMBIENT_FRESH_WINDOW_MS: number;
-/** A memory counts as high schema fit strictly above this. */
-export declare const HIGH_SCHEMA_FIT_ABOVE = 0.7;
 /** Row counts and sums an AmbientState is derived from; two stores' tallies add with addAmbientTallies. */
 export interface AmbientTallies {
     total: number;

package/dist/core/ambient.js

@@ -1,7 +1,10 @@
-/** Ambient state vector: a compact O(N) summary of the corpus telling 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, strengthAblation } from './ablation.js';
 import { Layer } from './memory.js';
-import { calculateStrength } from './memory.js';
+import { calculateStrength, HIGH_SCHEMA_FIT } 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.
@@ -22,8 +25,6 @@ const SUMMARY_THRESHOLD = {
 };
 /** 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);
@@ -68,7 +69,7 @@ export function tallyAmbientEntries(entries, now) {
             t.negative++;
         if (isErrorTagged(entry.tags))
             t.errors++;
-        if (entry.schema_fit > HIGH_SCHEMA_FIT_ABOVE)
+        if (entry.schema_fit > HIGH_SCHEMA_FIT)
             t.highSchemaFit++;
         if (entry.layer === Layer.Semantic)
             t.semantic++;
@@ -153,8 +154,9 @@ export function renderAmbientSummary(state) {
         parts.push('mostly episodic');
     if (state.extractionCoverage > T.extractionHigh)
         parts.push('high extraction coverage');
-    if (state.conflictIntensity > T.conflictShown)
+    if (state.conflictIntensity > T.conflictShown) {
         parts.push(`${(state.conflictIntensity * 100).toFixed(0)}% conflict rate`);
+    }
     if (state.dagDepth >= T.dagDepthShown)
         parts.push(`DAG depth ${state.dagDepth}`);
     if (state.avgStrength < T.strengthLow)

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

@@ -1,4 +1,6 @@
-/** Errors whose HTTP status is part of the API contract; the server maps by class, so message text can change freely. */
+/**
+ * Errors whose HTTP status is part of the API contract; the server maps by class, so message text can change freely.
+ */
 export type ApiErrorStatus = 400 | 403 | 404 | 409;
 /** Base class: an error the caller caused, carrying the status the HTTP layer answers with. */
 export declare abstract class ApiError extends Error {
@@ -24,8 +26,12 @@ 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`. */
+/**
+ * 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;

package/dist/core/api-errors.js

@@ -1,4 +1,6 @@
-/** Errors whose HTTP status is part of the API contract; the server maps by class, so message text can change freely. */
+/**
+ * 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 {
@@ -35,8 +37,12 @@ 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`. */
+/**
+ * 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;

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

@@ -54,7 +54,10 @@ 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. */
 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. */
+/**
+ * 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>;

package/dist/core/capture-contract.js

@@ -17,7 +17,10 @@ export function readClaudeCodePreCompact(stdinText, timedOut, runtime = 'claude-
     }
     const base = { runtime, event: 'pre-compact' };
     if (empty) {
-        return { status: 'received', input: { ...base, manual: true, sessionId: null, cwd: null, transcriptPath: null, trigger: null } };
+        return {
+            status: 'received',
+            input: { ...base, manual: true, sessionId: null, cwd: null, transcriptPath: null, trigger: null },
+        };
     }
     let payload;
     try {
@@ -31,7 +34,8 @@ export function readClaudeCodePreCompact(stdinText, timedOut, runtime = 'claude-
         return { status: 'skipped', reason: 'malformed or incomplete PreCompact payload (missing string transcript_path)' };
     }
     const transcriptPath = payload.transcript_path;
-    // Path shape only: CLAUDE_CONFIG_DIR can move the transcript root, and a same-user process can already read every transcript.
+    // Path shape only: CLAUDE_CONFIG_DIR can move the transcript root, and a same-user process can already read every
+    // transcript.
     if (!/\.jsonl$/i.test(transcriptPath)) {
         return { status: 'skipped', reason: `payload transcript_path is not a .jsonl file: ${transcriptPath}` };
     }
@@ -47,7 +51,10 @@ export function readClaudeCodePreCompact(stdinText, timedOut, runtime = 'claude-
         },
     };
 }
-/** 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. */
+/**
+ * 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 function readVscodeStop(stdinText, timedOut) {
     if (!stdinText || stdinText.trim() === '') {
         return timedOut
@@ -64,7 +71,9 @@ export function readVscodeStop(stdinText, timedOut) {
     if (!isObjectLike(payload) || !('hook_event_name' in payload) || payload.hook_event_name !== 'Stop') {
         return { status: 'skipped', reason: 'not a VS Code Stop payload (no snake_case hook_event_name "Stop")' };
     }
-    if (!('transcript_path' in payload) || !isStringValue(payload.transcript_path) || !/\.jsonl$/i.test(payload.transcript_path)) {
+    if (!('transcript_path' in payload) ||
+        !isStringValue(payload.transcript_path) ||
+        !/\.jsonl$/i.test(payload.transcript_path)) {
         return { status: 'skipped', reason: 'Stop payload names no .jsonl transcript_path' };
     }
     if (!('session_id' in payload) || !isStringValue(payload.session_id) || payload.session_id === '') {
@@ -96,7 +105,10 @@ export function readClaudeCodePostCompact(stdinText, timedOut) {
     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 === '') {
+    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 {
@@ -122,7 +134,10 @@ export function readSessionEnd(stdinText, timedOut, runtime = 'claude-code') {
     }
     const base = { runtime, event: 'session-end' };
     if (empty) {
-        return { status: 'received', input: { ...base, manual: true, sessionId: null, cwd: null, transcriptPath: null, trigger: null } };
+        return {
+            status: 'received',
+            input: { ...base, manual: true, sessionId: null, cwd: null, transcriptPath: null, trigger: null },
+        };
     }
     let payload;
     try {
@@ -140,9 +155,13 @@ export function readSessionEnd(stdinText, timedOut, runtime = 'claude-code') {
         input: {
             ...base,
             manual: false,
-            sessionId: 'session_id' in payload && isStringValue(payload.session_id) && payload.session_id !== '' ? payload.session_id : null,
+            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,
+            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,
         },

package/dist/core/compare.d.ts

@@ -1,5 +1,8 @@
-/** 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
+/**
+ * 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. */
@@ -10,8 +13,12 @@ export interface EntryIdentity {
     tags?: readonly string[];
     source?: string;
 }
-/** 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. */
+/**
+ * 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 } }`). */
@@ -19,13 +26,22 @@ export interface ScoredEntryLike {
     score: number;
     entry: EntryIdentity;
 }
-/** score descending, then `compareEntryIdentity`: the shared ordering for every score-primary recall sort site, which delegate here (via an arrow when the
+/**
+ * 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. */
+/**
+ * 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;
-/** 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. */
+/**
+ * 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,8 +1,15 @@
-/** 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
+/**
+ * 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. */
+/**
+ * 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) ||
@@ -36,12 +43,17 @@ function compareTags(a, b) {
     }
     return 0;
 }
-/** score descending, then `compareEntryIdentity`: the shared ordering for every score-primary recall sort site, which delegate here (via an arrow when the
+/**
+ * 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);
 }
-/** 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. */
+/**
+ * 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;
@@ -49,8 +61,12 @@ export function compareScoresDesc(a, b) {
         return 1;
     return Number(Number.isNaN(a)) - Number(Number.isNaN(b));
 }
-/** 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. */
+/**
+ * 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,7 +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 needing the provider's
+        /** 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
@@ -55,14 +56,16 @@ export interface HippoConfig {
     autoTraceCapture: boolean;
     /** Only promote sessions whose session_complete event is within N days. */
     autoTraceWindowDays: number;
-    /** Mid-session pinned-rule re-injection through the UserPromptSubmit hook: pinned memories are re-injected each turn within the 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
+        /** 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
@@ -79,8 +82,10 @@ export interface HippoConfig {
         /** FTS candidate pool size per store before gating. Default 100. */
         promptRecallCandidates: number;
     };
-    /** 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. */
+    /** 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';
@@ -100,12 +105,15 @@ export interface HippoConfig {
         enabled: boolean;
     };
     /** Opt-in learned memory-value rescue veto on the sleep decay pass. Default OFF: the frozen weights
-     *  (src/consolidate/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/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 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.
@@ -143,7 +151,8 @@ export interface HippoConfig {
 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. */
+ * 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/core/config.js

@@ -5,8 +5,8 @@ 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 { errorCode, errorMessage, log } from '../util/log.js';
+import { DEFAULT_LOCAL_BUMP, DEFAULT_MMR_LAMBDA, DEFAULT_RECALL_BUDGET } from './search-types.js';
+import { errorCode, errorMessage, log, errorFields } from '../util/log.js';
 import { isJsonObject } from '../util/json.js';
 export const DEFAULT_CONFIG = {
     defaultHalfLifeDays: DEFAULT_HALF_LIFE_DAYS,
@@ -35,7 +35,7 @@ export const DEFAULT_CONFIG = {
     physics: { ...DEFAULT_PHYSICS_CONFIG },
     mmr: {
         enabled: true,
-        lambda: 0.7,
+        lambda: DEFAULT_MMR_LAMBDA,
     },
     search: {
         localBump: DEFAULT_LOCAL_BUMP,
@@ -158,7 +158,8 @@ 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)) {
@@ -200,7 +201,8 @@ function churnStalenessEnabled(raw) {
     return enabled;
 }
 function defaultHalfLifeDays(raw) {
-    // Every writer starts a memory on this, and a zero or negative half-life scores zero strength, so sleep would retire it.
+    // Every writer starts a memory on this, and a zero or negative half-life scores zero strength, so sleep would retire
+    // it.
     const days = raw.defaultHalfLifeDays ?? DEFAULT_CONFIG.defaultHalfLifeDays;
     if (!Number.isFinite(days) || days <= 0) {
         log.warn(`config.json's "defaultHalfLifeDays" must be a number of days above 0 ` +
@@ -218,7 +220,8 @@ function sharedStoreFlag(raw) {
     return false;
 }
 export function loadConfig(hippoRoot) {
-    // A caller that names no folder, as an add-on serving another store does, gets the defaults, never the working folder's config.json.
+    // 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');
@@ -236,7 +239,8 @@ export function loadConfig(hippoRoot) {
 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. */
+/** 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 });
@@ -245,24 +249,33 @@ function fileStamp(file) {
     catch (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 });
+        if (code === 'EACCES' || code === 'EPERM') {
+            log.warnThenDebug(`config-unreachable:${file}:${code}`, message, { path: file, code, ...errorFields(err) });
+        }
+        // Any other refusal (ENOTDIR, ELOOP) means the path is simply not there, so only a permission refusal is told.
         else
-            log.debug(message);
+            log.debug(message, errorFields(err));
         return null;
     }
 }
-function parseConfigFile(configPath) {
+/** A config.json that exists must load: running on defaults would silently drop the user's settings, such as
+ * `sharedStore`. */
+function readConfigFile(configPath) {
+    let raw;
     try {
-        const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-        return configOverDefaults(raw);
+        raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
     }
     catch (err) {
-        if (fs.existsSync(configPath)) {
-            log.warn(`failed to parse ${configPath}: ${errorMessage(err)}`);
-        }
-        return { ...DEFAULT_CONFIG };
+        throw new Error(`${configPath} could not be loaded: ${errorMessage(err)}. Fix the file or delete it to use the defaults.`, { cause: err });
     }
+    if (!isJsonObject(raw)) {
+        throw new Error(`${configPath} must hold a JSON object. Fix the file or delete it to use the defaults.`);
+    }
+    // SAFETY: an object is all the shape check proves; configOverDefaults validates each key it reads.
+    return raw;
+}
+function parseConfigFile(configPath) {
+    return configOverDefaults(readConfigFile(configPath));
 }
 function configOverDefaults(raw) {
     const basis = raw.decayBasis;
@@ -312,20 +325,23 @@ function configOverDefaults(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. */
+/** The folder as isGlobalStoreRoot compares it (realpath, case-folded on Windows); its helper sits behind an import
+ * cycle. */
 function sharedStoreKey(hippoRoot) {
     let real;
     try {
         real = fs.realpathSync.native(hippoRoot);
     }
     catch (err) {
-        log.debug(`sharedStore: realpath fell back to resolve for ${hippoRoot}: ${errorMessage(err)}`);
+        // A folder that does not exist yet has no real path, so the resolved one stands in.
+        log.debug(`sharedStore: realpath fell back to resolve for ${hippoRoot}: ${errorMessage(err)}`, errorFields(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, so loadConfig's warnings stay loadConfig's. */
+ * 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))
@@ -334,15 +350,8 @@ export function isSharedStore(hippoRoot) {
     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}: ${errorMessage(err)} - sharedStore read as false.`);
-        return false;
-    }
-    if (raw?.sharedStore !== true) {
+    const raw = readConfigFile(configPath);
+    if (raw.sharedStore !== true) {
         if (notSharedStamps.size >= PARSED_CONFIGS_MAX)
             notSharedStamps.clear();
         notSharedStamps.set(configPath, stamp);

package/dist/core/cosine.d.ts

@@ -1,3 +1,6 @@
-/** Cosine over any indexable vectors (a Float32 view scores as its number[] copy); 0 for empty, mismatched or zero-norm input. */
+/**
+ * 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

@@ -1,4 +1,7 @@
-/** Cosine over any indexable vectors (a Float32 view scores as its number[] copy); 0 for empty, mismatched or zero-norm input. */
+/**
+ * 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;