hippo-memory 2.0.0 → 2.1.0

package/dist/consolidate/traces.js

@@ -1,17 +1,16 @@
 import { isRecallBoostAblated, strengthAblation } from '../core/ablation.js';
 import { Layer, createMemory, markRetrieved } from '../core/memory.js';
-import { findPromotableSessions, traceExistsForSession, listSessionEvents } from '../store/sessions.js';
-import { rejectionDigest } from '../store/rejection.js';
+import { rejectionDigest } from '../core/rejection-digest.js';
 import { sampleForReplay } from './replay.js';
 import { renderTraceContent } from './trace.js';
-import { resolveTenantId } from '../store/tenant.js';
-import { reportAuditWriteFailure } from '../store/audit.js';
+import { envTenant } from '../util/env.js';
 import { commonDerivationScope } from '../core/recall-scope.js';
 import { log } from '../util/log.js';
 import { REPLAY_COUNT_DEFAULT } from './run.js';
 import { isJsonString } from '../util/json.js';
 import { DAY_MS } from '../util/time.js';
-// 1.4. Auto-promote complete sessions to traces: each session in the window with a `session_complete` event and no trace (idempotent via source_session_id)
+// 1.4. Auto-promote complete sessions to traces: each session in the window with a `session_complete` event and no
+// trace (idempotent via source_session_id)
 // is rendered as markdown and persisted as a Layer.Trace memory, which inherits decay, search, replay and physics.
 export function promoteSessionTraces(run) {
     const { result } = run;
@@ -22,8 +21,8 @@ export function promoteSessionTraces(run) {
     const sinceMs = run.now.getTime() - windowDays * DAY_MS;
     // Auto-trace runs single-tenant (the env-resolved tenant); consolidating
     // every tenant needs a per-tenant loop layered on top of this.
-    const consolidationTenant = resolveTenantId({});
-    const promotable = findPromotableSessions(run.hippoRoot, consolidationTenant, sinceMs);
+    const consolidationTenant = envTenant();
+    const promotable = run.store.promotableSessions(consolidationTenant, sinceMs);
     for (const session of promotable) {
         const built = sessionTrace(run, consolidationTenant, session.session_id);
         if (!built)
@@ -39,7 +38,8 @@ export function promoteSessionTraces(run) {
         result.details.push(`  🧬 promoted trace ${trace.id} from session ${session.session_id} (${outcome})`);
     }
     if (result.promotedTraces > 0) {
-        result.details.push(`  🧬 promoted ${result.promotedTraces} trace${result.promotedTraces === 1 ? '' : 's'} from completed session${result.promotedTraces === 1 ? '' : 's'}`);
+        result.details.push(`  🧬 promoted ${result.promotedTraces} trace${result.promotedTraces === 1 ? '' : 's'} from completed ` +
+            `session${result.promotedTraces === 1 ? '' : 's'}`);
     }
     if (tracesSkippedRejected > 0) {
         log.warn(`consolidate: skipped ${tracesSkippedRejected} auto-promoted trace(s) whose content matches a rejected value`);
@@ -48,9 +48,9 @@ export function promoteSessionTraces(run) {
 /** The trace a completed session renders to, or null when it already has one or cannot be promoted. */
 function sessionTrace(run, consolidationTenant, sessionId) {
     // Idempotency: skip if a trace for this session already exists.
-    if (traceExistsForSession(run.hippoRoot, consolidationTenant, sessionId))
+    if (run.store.traceExists(consolidationTenant, sessionId))
         return null;
-    const events = listSessionEvents(run.hippoRoot, consolidationTenant, {
+    const events = run.store.sessionEvents(consolidationTenant, {
         session_id: sessionId,
         limit: 1000,
     });
@@ -70,8 +70,8 @@ function sessionTrace(run, consolidationTenant, sessionId) {
         .map((e) => ({ action: e.content, observation: '' }));
     const trace = createMemory(renderTraceContent({ task: summary, steps, outcome }), {
         layer: Layer.Trace,
-        trace_outcome: outcome,
-        source_session_id: sessionId,
+        traceOutcome: outcome,
+        sourceSessionId: sessionId,
         tags: ['auto-promoted'],
         source: 'auto-promote',
         scope: sessionScope.scope,
@@ -106,29 +106,26 @@ function traceRejected(run, trace, sessionId) {
     const tombstone = run.tombstones.find(trace.tenant_id, traceDigest);
     if (!tombstone)
         return false;
-    try {
-        run.tombstones.audit({
-            tenantId: trace.tenant_id,
-            actor: 'sleep',
-            op: 'reject_refusal',
-            metadata: {
-                digest: traceDigest,
-                reason: tombstone.reason,
-                sourceSessionId: sessionId,
-            },
-        });
-    }
-    catch (error) {
-        reportAuditWriteFailure('reject_refusal', String(error));
-    }
+    run.tombstones.auditOrCount({
+        tenantId: trace.tenant_id,
+        actor: 'sleep',
+        op: 'reject_refusal',
+        metadata: {
+            digest: traceDigest,
+            reason: tombstone.reason,
+            sourceSessionId: sessionId,
+        },
+    });
     return true;
 }
-// 1.5. Replay pass: rehearse high-value survivors by sampling N memories weighted by outcome, valence, under-rehearsal and idle time,
+// 1.5. Replay pass: rehearse high-value survivors by sampling N memories weighted by outcome, valence, under-rehearsal
+// and idle time,
 // then applying the `markRetrieved` strengthening, so important memories don't fade.
 export function replayPass(run) {
     const { survivors, now } = run;
     const replayCount = run.config.replay?.count ?? REPLAY_COUNT_DEFAULT;
-    // EVAL-ONLY ablation (see ablation.ts): replay rehearsal is recall strengthening, so the strengthen-off arm silences the whole pass;
+    // EVAL-ONLY ablation (see ablation.ts): replay rehearsal is recall strengthening, so the strengthen-off arm silences
+    // the whole pass;
     // persisting unmutated entries anyway would still refresh updated_at and mirrors.
     if (!(replayCount > 0 && survivors.length > 0 && !isRecallBoostAblated()))
         return;

package/dist/core/ablation.d.ts

@@ -1,5 +1,8 @@
-/** 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. */
 /** The three switches strength scoring honours, resolved by the entry layer and handed to core in DecayOptions. */
 export interface StrengthAblation {
@@ -18,7 +21,10 @@ 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; 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 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,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;