hippo-memory 1.59.0 → 1.61.0

package/dist/index.d.ts

@@ -5,22 +5,41 @@ import { type CreateMemoryOptions, type MemoryEntry } from './memory.js';
 export { MemoryEntry, Layer, EmotionalValence, ConfidenceLevel, DecayOptions, calculateStrength, resolveConfidence, confidenceFacets, type ConfidenceFacets, applyOutcome, generateId, computeSchemaFit } from './memory.js';
 /** Published signature, so `baseHalfLifeDays` stays optional here; hippo's own writers use the strict one in memory.ts. */
 export declare function createMemory(content: string, options?: Partial<CreateMemoryOptions>): MemoryEntry;
-export { search, hybridSearch, physicsSearch, estimateTokens, textOverlap, explainMatch, detectTemporalDirection, temporalBoost, computeTemporalRange, SearchResult, MatchExplanation } from './search.js';
-export { tokenize } from './tokenize.js';
+export { search } from './search/bm25-search.js';
+export { hybridSearch } from './search/hybrid.js';
+export { physicsSearch } from './search/physics-search.js';
+export { explainMatch, MatchExplanation } from './search/explain.js';
+export { detectTemporalDirection, temporalBoost, computeTemporalRange } from './search/temporal.js';
+export { SearchResult } from './search/types.js';
+export { estimateTokens } from './token-ledger.js';
+export { tokenize, textOverlap } from './tokenize.js';
 export { markRetrieved } from './memory.js';
 export { multihopSearch } from './multihop.js';
 export { graphExpandRecall, MAX_HOPS, DEFAULT_MAX_NEIGHBORS, type GraphExpandOpts } from './graph-recall.js';
-export { initStore, loadAllEntries, loadSearchEntries, loadRecallSearchEntries, writeEntry, readEntry, deleteEntry, loadIndex, rebuildIndex, saveActiveTaskSnapshot, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, SNAPSHOT_AMBIENT_MAX_AGE_MS, closeTaskSnapshotsForSession, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, listMemoryConflicts, replaceDetectedConflicts, resolveConflict, saveSessionHandoff, loadLatestHandoff, loadHandoffById, stampHandoffOutcome, writeSessionEndHandoff, loadSessionDecayContext, SessionDecayContext, } from './store.js';
+export { initStore } from './store/open.js';
+export { writeEntry } from './store/entry-writes.js';
+export { loadAllEntries, readEntry } from './store/entry-reads.js';
+export { deleteEntry } from './store/delete-and-batch.js';
+export { loadSearchEntries, loadRecallSearchEntries } from './store/search-rows.js';
+export { loadIndex, rebuildIndex, loadSessionDecayContext, SessionDecayContext } from './store/index-and-stats.js';
+export { saveActiveTaskSnapshot, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, SNAPSHOT_AMBIENT_MAX_AGE_MS, closeTaskSnapshotsForSession, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, } from './store/sessions.js';
+export { listMemoryConflicts, replaceDetectedConflicts, resolveConflict } from './store/conflicts.js';
+export { saveSessionHandoff, loadLatestHandoff, loadHandoffById, stampHandoffOutcome, writeSessionEndHandoff, } from './store/handoffs.js';
 export { createCard, loadCard, listCards, loadCardDeps, loadCardRuns, loadCardComments, claimCard, heartbeatCard, blockCard, reviewCard, completeCard, reclaimExpiredCards, addCardComment, loadLatestHandoffForCard, } from './store-cards.js';
 export { SessionHandoff, HandoffOutcome, HandoffEvidence, isHandoffOutcome } from './handoff.js';
 export { Card, CardStatus, CardRun, CardComment, CardTransitions, isCardStatus, CARD_TRANSITIONS, CARD_LEASE_MS } from './card.js';
-export { consolidate, ConsolidationResult } from './consolidate.js';
+export { consolidate } from './consolidate/sleep.js';
+export { ConsolidationResult } from './consolidate/run.js';
 export { strengthBucket } from './dedupe.js';
-export { isEmbeddingAvailable, getEmbedding, cosineSimilarity, loadEmbeddingIndex, saveEmbeddingIndex, embedMemory, embedAll, } from './embeddings.js';
+export { isEmbeddingAvailable, getEmbedding } from './local-embedding.js';
+export { cosineSimilarity, loadEmbeddingIndex, saveEmbeddingIndex, embedMemory, embedAll, } from './embeddings.js';
 export { captureError, extractLessons, partitionLessons, deduplicateLesson, runWatched, fetchGitLog, } from './autolearn.js';
 export { getGlobalRoot, initGlobal, promoteToGlobal, searchBoth, searchBothHybrid, syncGlobalToLocal, HybridSearchOptions, transferScore, shareMemory, listPeers, autoShare, } from './shared.js';
 export { wmPush, wmRead, wmClear, wmFlush, WorkingMemoryItem, WM_MAX_ENTRIES, } from './working-memory.js';
-export { importChatGPT, importClaude, importCursor, importGenericFile, importMarkdown, importVault, importEntries, ImportResult, ImportOptions, } from './importers.js';
+export { importChatGPT, importClaude, importCursor, importGenericFile, } from './importers/sources.js';
+export { importMarkdown } from './importers/markdown.js';
+export { importVault } from './importers/vault.js';
+export { importEntries, ImportResult, ImportOptions } from './importers/core.js';
 export { runFeatureEval, formatResult, resultToBaseline, detectRegressions, buildSyntheticCorpus, } from './eval-suite.js';
 export { computeSalience, SalienceDecision, SalienceResult, SalienceOptions, } from './salience.js';
 export { computeAmbientState, renderAmbientSummary, formatAmbientVector, AmbientState, } from './ambient.js';

package/dist/index.js

@@ -7,22 +7,36 @@ export { Layer, calculateStrength, resolveConfidence, confidenceFacets, applyOut
 export function createMemory(content, options = {}) {
     return createStoreMemory(content, { ...options, baseHalfLifeDays: options.baseHalfLifeDays ?? DEFAULT_HALF_LIFE_DAYS });
 }
-export { search, hybridSearch, physicsSearch, estimateTokens, textOverlap, explainMatch, detectTemporalDirection, temporalBoost, computeTemporalRange } from './search.js';
-export { tokenize } from './tokenize.js';
+export { search } from './search/bm25-search.js';
+export { hybridSearch } from './search/hybrid.js';
+export { physicsSearch } from './search/physics-search.js';
+export { explainMatch } from './search/explain.js';
+export { detectTemporalDirection, temporalBoost, computeTemporalRange } from './search/temporal.js';
+export { estimateTokens } from './token-ledger.js';
+export { tokenize, textOverlap } from './tokenize.js';
 export { markRetrieved } from './memory.js';
 export { multihopSearch } from './multihop.js';
 export { graphExpandRecall, MAX_HOPS, DEFAULT_MAX_NEIGHBORS } from './graph-recall.js';
-export { initStore, loadAllEntries, loadSearchEntries, loadRecallSearchEntries, writeEntry, readEntry, deleteEntry, loadIndex, rebuildIndex, saveActiveTaskSnapshot, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, SNAPSHOT_AMBIENT_MAX_AGE_MS, closeTaskSnapshotsForSession, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, listMemoryConflicts, replaceDetectedConflicts, resolveConflict, saveSessionHandoff, loadLatestHandoff, loadHandoffById, stampHandoffOutcome, writeSessionEndHandoff, loadSessionDecayContext, } from './store.js';
+export { initStore } from './store/open.js';
+export { writeEntry } from './store/entry-writes.js';
+export { loadAllEntries, readEntry } from './store/entry-reads.js';
+export { deleteEntry } from './store/delete-and-batch.js';
+export { loadSearchEntries, loadRecallSearchEntries } from './store/search-rows.js';
+export { loadIndex, rebuildIndex, loadSessionDecayContext } from './store/index-and-stats.js';
+export { saveActiveTaskSnapshot, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, SNAPSHOT_AMBIENT_MAX_AGE_MS, closeTaskSnapshotsForSession, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, } from './store/sessions.js';
+export { listMemoryConflicts, replaceDetectedConflicts, resolveConflict } from './store/conflicts.js';
+export { saveSessionHandoff, loadLatestHandoff, loadHandoffById, stampHandoffOutcome, writeSessionEndHandoff, } from './store/handoffs.js';
 export { createCard, loadCard, listCards, loadCardDeps, loadCardRuns, loadCardComments, claimCard, heartbeatCard, blockCard, reviewCard, completeCard, reclaimExpiredCards, addCardComment, loadLatestHandoffForCard, } from './store-cards.js';
 // Feature 5: Session handoff
 export { isHandoffOutcome } from './handoff.js';
 // W2a: work-queue cards
 export { isCardStatus, CARD_TRANSITIONS, CARD_LEASE_MS } from './card.js';
-export { consolidate } from './consolidate.js';
+export { consolidate } from './consolidate/sleep.js';
 // Announced public in CHANGELOG 1.26.3 but never re-exported; the rest of dedupe.js stays internal.
 export { strengthBucket } from './dedupe.js';
 // Feature 1: Embedding search
-export { isEmbeddingAvailable, getEmbedding, cosineSimilarity, loadEmbeddingIndex, saveEmbeddingIndex, embedMemory, embedAll, } from './embeddings.js';
+export { isEmbeddingAvailable, getEmbedding } from './local-embedding.js';
+export { cosineSimilarity, loadEmbeddingIndex, saveEmbeddingIndex, embedMemory, embedAll, } from './embeddings.js';
 // Feature 2: Auto-learn from errors
 export { captureError, extractLessons, partitionLessons, deduplicateLesson, runWatched, fetchGitLog, } from './autolearn.js';
 // Feature 3: Cross-agent shared memory
@@ -30,7 +44,10 @@ export { getGlobalRoot, initGlobal, promoteToGlobal, searchBoth, searchBothHybri
 // Feature 5: Working memory
 export { wmPush, wmRead, wmClear, wmFlush, WM_MAX_ENTRIES, } from './working-memory.js';
 // Feature 4: Memory importers
-export { importChatGPT, importClaude, importCursor, importGenericFile, importMarkdown, importVault, importEntries, } from './importers.js';
+export { importChatGPT, importClaude, importCursor, importGenericFile, } from './importers/sources.js';
+export { importMarkdown } from './importers/markdown.js';
+export { importVault } from './importers/vault.js';
+export { importEntries } from './importers/core.js';
 // Feature eval suite
 export { runFeatureEval, formatResult, resultToBaseline, detectRegressions, buildSyntheticCorpus, } from './eval-suite.js';
 // Pineal gland: salience gate

package/dist/invalidation.js

@@ -1,4 +1,5 @@
-import { loadAllEntries, readEntry, writeEntry } from './store.js';
+import { writeEntry } from './store/entry-writes.js';
+import { loadAllEntries, readEntry } from './store/entry-reads.js';
 import { openHippoDb, closeHippoDb } from './db.js';
 import { CHURN_STALE_TAG } from './memory.js';
 import { GitReadError, gitLsFilesAtHead, fetchChurnWindowLog, gitGrepPresence, resolveCommitBefore, packageScriptsAt, } from './churn-git.js';

package/dist/judgment.js

@@ -1,7 +1,9 @@
 /** Typed judgment over capture candidates via TypeSafe's Jev (System One).
  *  Regex picks WHAT is a candidate; it cannot say what is worth keeping, so
  *  every captured memory currently lands on a flat schema_fit of 0.5. */
+import { envTypesafeApiKey } from './env.js';
 import { fetchWithRetry } from './http-retry.js';
+import { log } from './log.js';
 const ENDPOINT = 'https://api.typesafe.ai/v1/systemone';
 const DEFAULT_MODEL = 'jev-1.13.0';
 const MAX_CONCURRENCY = 8;
@@ -36,7 +38,7 @@ const KINDS = ['error', 'decision', 'convention', 'preference', 'trivia'];
 const VALENCES = ['critical', 'negative', 'positive', 'neutral'];
 /** Absent key means hippo keeps its pre-Jev behaviour and makes no HTTP call. */
 export function judgmentApiKey() {
-    const key = process.env.TYPESAFE_API_KEY?.trim();
+    const key = envTypesafeApiKey()?.trim();
     return key ? key : undefined;
 }
 function oneOf(value, allowed) {
@@ -66,7 +68,8 @@ async function post(content, opts) {
             }),
         }, { timeoutMs: JUDGE_TIMEOUT_MS, fetchFn: opts.fetcher });
     }
-    catch {
+    catch (err) {
+        log.debug(`judge: request failed: ${err instanceof Error ? err.message : String(err)}`);
         return null;
     }
     return res.ok ? res : null;
@@ -87,7 +90,8 @@ export async function judge(content, opts) {
         // optional-chained and range-checked before use, so a lie here returns null.
         data = await res.json();
     }
-    catch {
+    catch (err) {
+        log.debug(`judge: unreadable response: ${err instanceof Error ? err.message : String(err)}`);
         return null;
     }
     const durable = data.answers?.durable?.noul;

package/dist/keyset.d.ts

@@ -0,0 +1,13 @@
+/** The sort key and id of the last row a page returned. */
+export interface KeysetPosition {
+    readonly key: string | number;
+    readonly id: string | number;
+}
+/** A WHERE fragment and the params it binds. */
+export interface KeysetClause {
+    sql: string;
+    params: Array<string | number>;
+}
+/** An ` AND ...` WHERE fragment and its params selecting rows strictly after `after`; empty when `after` is unset. */
+export declare function keysetAfter(sortCol: string, idCol: string, after: KeysetPosition | undefined): KeysetClause;
+//# sourceMappingURL=keyset.d.ts.map

package/dist/keyset.js

@@ -0,0 +1,8 @@
+// Keyset paging for list queries ordered by (sort key DESC, id DESC), so a page never skips or repeats a row when rows arrive between requests.
+/** An ` AND ...` WHERE fragment and its params selecting rows strictly after `after`; empty when `after` is unset. */
+export function keysetAfter(sortCol, idCol, after) {
+    if (!after)
+        return { sql: '', params: [] };
+    return { sql: ` AND (${sortCol}, ${idCol}) < (?, ?)`, params: [after.key, after.id] };
+}
+//# sourceMappingURL=keyset.js.map

package/dist/local-embedding.d.ts

@@ -0,0 +1,13 @@
+export declare const DEFAULT_EMBEDDING_MODEL = "Xenova/all-MiniLM-L6-v2";
+/** BGE was trained with CLS pooling; everything else gets mean, the sentence-transformers default, since CLS degrades mean-trained models. */
+export declare function poolingFor(model: string): 'cls' | 'mean';
+/** `query` is search input, `passage` is a document being indexed; no role means no prefix on any model. */
+export type EmbeddingRole = 'query' | 'passage';
+/** e5 models only match a query to a passage when each side carries its trained prefix. */
+export declare function prefixFor(model: string, role?: EmbeddingRole): string;
+/** Check (synchronously) if @xenova/transformers or @huggingface/transformers is installed. */
+export declare function isEmbeddingAvailable(): boolean;
+export declare function resolveEmbeddingModel(hippoRoot: string, explicitModel?: string): string;
+/** Embeds `text` with the local model, or returns `[]` when Transformers.js is missing or fails; `role` adds e5-style prefixes. */
+export declare function getEmbedding(text: string, model?: string, role?: EmbeddingRole): Promise<number[]>;
+//# sourceMappingURL=local-embedding.d.ts.map

package/dist/local-embedding.js

@@ -0,0 +1,165 @@
+// The local Transformers.js embedder, a leaf so embedding-provider.ts can wrap it without importing embeddings.ts.
+import { envModelCache } from './env.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import { createRequire } from 'module';
+import { loadConfig } from './config.js';
+import { log } from './log.js';
+const _require = createRequire(import.meta.url);
+let _embeddingAvailable = null;
+// A pipeline is expensive to load, so one instance per model is kept for the process.
+const _pipelineInstances = new Map();
+const _pipelineLoading = new Map();
+export const DEFAULT_EMBEDDING_MODEL = 'Xenova/all-MiniLM-L6-v2';
+/** BGE was trained with CLS pooling; everything else gets mean, the sentence-transformers default, since CLS degrades mean-trained models. */
+export function poolingFor(model) {
+    return /\bbge\b/i.test(model) ? 'cls' : 'mean';
+}
+/** e5 models only match a query to a passage when each side carries its trained prefix. */
+export function prefixFor(model, role) {
+    if (!role)
+        return '';
+    if (/\be5\b/i.test(model)) {
+        return role === 'query' ? 'query: ' : 'passage: ';
+    }
+    return '';
+}
+// Use Function constructor to bypass TypeScript static module resolution
+// for optional peer dependencies that may not be installed.
+// SAFETY: `import(s)` always resolves to a module namespace object (or rejects);
+// Promise<object> names that honestly without claiming a specific module shape.
+const _dynImport = new Function('s', 'return import(s)');
+/** Check (synchronously) if @xenova/transformers or @huggingface/transformers is installed. */
+export function isEmbeddingAvailable() {
+    if (_embeddingAvailable !== null)
+        return _embeddingAvailable;
+    try {
+        _require.resolve('@xenova/transformers');
+        _embeddingAvailable = true;
+        return true;
+    }
+    catch {
+        // fall through
+    }
+    try {
+        _require.resolve('@huggingface/transformers');
+        _embeddingAvailable = true;
+        return true;
+    }
+    catch {
+        // fall through
+    }
+    _embeddingAvailable = false;
+    return false;
+}
+// Importing both packages loads two incompatible onnxruntime-node builds whose finalizers can double-free on exit,
+// so pick one first: the maintained package hippo ships, with Xenova only as a fallback a user installed.
+function resolveTransformersPackage() {
+    try {
+        _require.resolve('@huggingface/transformers');
+        return '@huggingface/transformers';
+    }
+    catch {
+        // fall through
+    }
+    try {
+        _require.resolve('@xenova/transformers');
+        return '@xenova/transformers';
+    }
+    catch {
+        return null; // neither optional package is installed; callers fall back to no local embeddings
+    }
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function loadPipeline(model) {
+    if (_pipelineInstances.has(model))
+        return _pipelineInstances.get(model);
+    if (_pipelineLoading.has(model))
+        return _pipelineLoading.get(model);
+    const loading = (async () => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const pkg = resolveTransformersPackage();
+        if (!pkg)
+            return null;
+        let pipelineFn = null;
+        try {
+            // SAFETY: the resolved module's shape is untyped by design (optional peer
+            // dependency); pipelineFn/mod.env are read defensively below and any
+            // failure to find a usable pipeline falls through to `return null`.
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const mod = await _dynImport(pkg);
+            if (envModelCache()) {
+                if (mod.env) {
+                    mod.env.cacheDir = envModelCache();
+                    mod.env.localModelPath = envModelCache();
+                    mod.env.allowRemoteModels = false;
+                }
+            }
+            pipelineFn = mod.pipeline ?? mod.default?.pipeline;
+        }
+        catch (err) {
+            log.debug(`transformers import failed (${pkg}): ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+        if (!pipelineFn)
+            return null;
+        // The offline bundle used in egress-blocked sandboxes ships only the FP32 model, so use whichever file is on disk.
+        const cacheRoot = envModelCache()?.trim();
+        const quantized = !cacheRoot
+            || fs.existsSync(path.join(cacheRoot, model, 'onnx', 'model_quantized.onnx'));
+        try {
+            const instance = await pipelineFn('feature-extraction', model, { quantized });
+            _pipelineInstances.set(model, instance);
+            return instance;
+        }
+        catch (err) {
+            log.debug(`embedding pipeline load failed (${model}): ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+        finally {
+            _pipelineLoading.delete(model);
+        }
+    })();
+    _pipelineLoading.set(model, loading);
+    return loading;
+}
+export function resolveEmbeddingModel(hippoRoot, explicitModel) {
+    const direct = explicitModel?.trim();
+    if (direct)
+        return direct;
+    try {
+        const configured = loadConfig(hippoRoot).embeddings.model?.trim();
+        if (configured)
+            return configured;
+    }
+    catch {
+        // Fall back to the default model when config cannot be read.
+    }
+    return DEFAULT_EMBEDDING_MODEL;
+}
+/** Embeds `text` with the local model, or returns `[]` when Transformers.js is missing or fails; `role` adds e5-style prefixes. */
+export async function getEmbedding(text, model = DEFAULT_EMBEDDING_MODEL, role) {
+    if (!isEmbeddingAvailable())
+        return [];
+    try {
+        const pipe = await loadPipeline(model);
+        if (!pipe)
+            return [];
+        const prefix = prefixFor(model, role);
+        const input = prefix ? `${prefix}${text}` : text;
+        // SAFETY: pipe() is a Transformers.js feature-extraction pipeline call;
+        // its untyped output is read defensively below (only `.data`, cast on
+        // the return line to the documented Float32Array tensor shape).
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const output = await pipe(input, { pooling: poolingFor(model), normalize: true });
+        // SAFETY: output.data is a Float32Array per the feature-extraction
+        // pipeline's documented tensor output shape.
+        return Array.from(output.data);
+    }
+    catch (err) {
+        // The caller sees `[]` and names the memory; the reason only shows at debug.
+        log.debug(`local embedding failed: ${err instanceof Error ? err.message : String(err)}`);
+        return [];
+    }
+}
+//# sourceMappingURL=local-embedding.js.map

package/dist/log.d.ts

@@ -12,13 +12,20 @@ export declare function isLevelEnabled(level: LogLevel): boolean;
 export declare function formatLogLine(level: LogLevel, message: string, fields?: LogFields): string;
 /** Write `message` at `level` the first time `key` is seen in this process; later calls are dropped. */
 declare function once(key: string, level: LogLevel, message: string, fields?: LogFields): void;
+/** Warn the first time `key` is seen in this process, then log at debug, so a repeating failure stays findable without flooding stderr. */
+declare function warnThenDebug(key: string, message: string, fields?: LogFields): void;
+/** The class name and stack of a thrown value, as log fields; a non-Error throw has no stack. */
+export declare function errorFields<E>(err: E): LogFields;
 export declare const log: {
     readonly error: (message: string, fields?: LogFields) => void;
     readonly warn: (message: string, fields?: LogFields) => void;
     readonly info: (message: string, fields?: LogFields) => void;
     readonly debug: (message: string, fields?: LogFields) => void;
     readonly once: typeof once;
+    readonly warnThenDebug: typeof warnThenDebug;
 };
+/** Message for a caught value of unknown shape. `cause` names the sanctioned unknown-input case (error-cause enrichment). */
+export declare function errorMessage(cause: unknown): string;
 /** Test hook: forget which once-keys have fired. */
 export declare function resetLogOnce(): void;
 export {};

package/dist/log.js

@@ -1,11 +1,12 @@
 /** Leveled stderr logger. `HIPPO_LOG` picks the threshold (error, warn, info, debug); unset or unknown means warn. */
+import { envLogLevel } from './env.js';
 const RANK = { error: 0, warn: 1, info: 2, debug: 3 };
 function isLogLevel(value) {
     return Object.hasOwn(RANK, value);
 }
 /** The active threshold, read on every call so a test or a long-lived server can change it without a restart. */
 export function logThreshold() {
-    const raw = process.env.HIPPO_LOG?.trim().toLowerCase() ?? '';
+    const raw = envLogLevel();
     return isLogLevel(raw) ? raw : 'warn';
 }
 export function isLevelEnabled(level) {
@@ -34,13 +35,30 @@ function once(key, level, message, fields) {
     onceKeys.add(key);
     write(level, message, fields);
 }
+/** Warn the first time `key` is seen in this process, then log at debug, so a repeating failure stays findable without flooding stderr. */
+function warnThenDebug(key, message, fields) {
+    const level = onceKeys.has(key) ? 'debug' : 'warn';
+    onceKeys.add(key);
+    write(level, message, fields);
+}
+/** The class name and stack of a thrown value, as log fields; a non-Error throw has no stack. */
+export function errorFields(err) {
+    if (!(err instanceof Error))
+        return { errorClass: 'NonError' };
+    return { errorClass: err.constructor.name, stack: err.stack };
+}
 export const log = {
     error: (message, fields) => write('error', message, fields),
     warn: (message, fields) => write('warn', message, fields),
     info: (message, fields) => write('info', message, fields),
     debug: (message, fields) => write('debug', message, fields),
     once,
+    warnThenDebug,
 };
+/** Message for a caught value of unknown shape. `cause` names the sanctioned unknown-input case (error-cause enrichment). */
+export function errorMessage(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
 /** Test hook: forget which once-keys have fired. */
 export function resetLogOnce() {
     onceKeys.clear();

package/dist/mcp/admin-tools.d.ts

@@ -0,0 +1,8 @@
+import { type ToolCall } from './protocol.js';
+export declare function runPredictBaserateTool({ args, ctx, hippoRoot, tenantId }: ToolCall): string;
+export declare function runStatusTool({ hippoRoot, config, tenantId }: ToolCall): string;
+export declare function runConflictsTool({ hippoRoot, tenantId }: ToolCall): string;
+export declare function runResolveTool({ args, ctx, hippoRoot, tenantId }: ToolCall): string;
+export declare function runShareTool({ args, hippoRoot, tenantId }: ToolCall): string;
+export declare function runPeersTool({ tenantId }: ToolCall): string;
+//# sourceMappingURL=admin-tools.d.ts.map

package/dist/mcp/admin-tools.js

@@ -0,0 +1,116 @@
+// Store health and admin tool handlers: base rates, status, conflicts, resolve, share and peers.
+import { calculateStrength } from '../memory.js';
+import { evalNow } from '../ablation.js';
+import { loadStrengthRows } from '../store/candidates.js';
+import { listMemoryConflicts, resolveConflict } from '../store/conflicts.js';
+import { shareMemory, listPeers } from '../shared.js';
+import { computePredictionBaserate } from '../predictions/store.js';
+import { isJsonString } from './protocol.js';
+export function runPredictBaserateTool({ args, ctx, hippoRoot, tenantId }) {
+    // J3 reference-class / planning-fallacy detector. Reads from the E2
+    // predictions table; returns text-only response matching the existing
+    // MCP tool convention (no structured JSON over the wire). Direct call
+    // to computePredictionBaserate; helper opens its own db + emits audit
+    // (single source of truth, no caller-site drift).
+    const classTag = String(args.class_tag || '').trim();
+    if (!classTag)
+        return 'No class_tag provided. Usage: pass class_tag matching a class used in past predictions (e.g. "migration-effort").';
+    const baserate = computePredictionBaserate(hippoRoot, tenantId, classTag, ctx?.actor ?? 'mcp');
+    if (baserate.nClosed === 0) {
+        return `No closed predictions in class "${classTag}" yet. Create one via hippo_predict (or 'hippo predict ...' CLI) and close it with hippo_predict_close once the actual outcome is known. Base rates need closed predictions with numeric actual_value to compute.`;
+    }
+    const lines = [baserate.summary, ''];
+    lines.push(`n_closed:         ${baserate.nClosed}`);
+    lines.push(`n_ratio_eligible: ${baserate.nRatioEligible}`);
+    if (baserate.meanEstimate !== null)
+        lines.push(`mean_estimate:    ${baserate.meanEstimate.toFixed(3)}`);
+    if (baserate.meanActual !== null)
+        lines.push(`mean_actual:      ${baserate.meanActual.toFixed(3)}`);
+    if (baserate.meanRatio !== null)
+        lines.push(`mean_ratio:       ${baserate.meanRatio.toFixed(3)}x`);
+    if (baserate.p50Ratio !== null)
+        lines.push(`p50_ratio:        ${baserate.p50Ratio.toFixed(3)}x`);
+    if (baserate.mae !== null)
+        lines.push(`mae:              ${baserate.mae.toFixed(3)}`);
+    return lines.join('\n');
+}
+export function runStatusTool({ hippoRoot, config, tenantId }) {
+    // Every row counts toward the averages, so this scans the store, but without its text.
+    const entries = loadStrengthRows(hippoRoot, tenantId);
+    const now = evalNow(); // honors HIPPO_FAKE_NOW (eval-only; see ablation.ts)
+    let atRisk = 0;
+    let totalStrength = 0;
+    for (const e of entries) {
+        const s = calculateStrength(e, now);
+        totalStrength += s;
+        if (s < 0.1 && !e.pinned)
+            atRisk++;
+    }
+    const avgStrength = entries.length > 0 ? (totalStrength / entries.length).toFixed(2) : '0';
+    const pinned = entries.filter((e) => e.pinned).length;
+    const errors = entries.filter((e) => e.tags.includes('error')).length;
+    const conflicts = listMemoryConflicts(hippoRoot, 'open', tenantId).length;
+    return [
+        `Memories: ${entries.length} (${pinned} pinned, ${errors} errors)`,
+        `Avg strength: ${avgStrength}`,
+        `At risk (<0.1): ${atRisk}`,
+        `Open conflicts: ${conflicts}`,
+        `Half-life default: ${config.defaultHalfLifeDays}d`,
+    ].join('\n');
+}
+export function runConflictsTool({ hippoRoot, tenantId }) {
+    const conflicts = listMemoryConflicts(hippoRoot, 'open', tenantId);
+    if (conflicts.length === 0)
+        return 'No open conflicts.';
+    return conflicts.map((c) => `conflict_${c.id}: ${c.memory_a_id} <-> ${c.memory_b_id} (score=${c.score.toFixed(2)}) — ${c.reason}`).join('\n');
+}
+export function runResolveTool({ args, ctx, hippoRoot, tenantId }) {
+    const conflictId = Number(args.conflict_id);
+    const keepId = String(args.keep || '');
+    const forget = Boolean(args.forget);
+    // AT1: optional rejectLoser + reason, threaded straight through to
+    // resolveConflict's opts (plan §5 — mirrors the CLI's --reject-loser).
+    const rejectLoser = Boolean(args.rejectLoser);
+    const reason = isJsonString(args.reason) ? args.reason : undefined;
+    if (isNaN(conflictId) || !keepId)
+        return 'Required: conflict_id and keep.';
+    const result = resolveConflict(hippoRoot, conflictId, keepId, forget, tenantId, {
+        rejectLoserValue: rejectLoser,
+        reason,
+        // P2 fix: resolveConflict's opts.rejectedBy defaults to 'cli' when
+        // omitted — this call site never passed it, so the tombstone's
+        // rejected_by AND the conflict_resolve audit's actor both landed as
+        // 'cli' even though the caller was MCP. ctx.actor carries the
+        // auth-resolved actor for HTTP-MCP (see McpContext above); stdio
+        // callers pass no ctx, so 'mcp' is the honest fallback there.
+        rejectedBy: ctx?.actor ?? 'mcp',
+    });
+    if (!result)
+        return 'Could not resolve. Check the conflict ID and --keep value.';
+    const action = rejectLoser ? 'rejected (tombstoned) and removed' : forget ? 'deleted' : 'weakened';
+    return `Resolved conflict ${conflictId}: kept ${keepId}, ${action} ${result.loserId}`;
+}
+export function runShareTool({ args, hippoRoot, tenantId }) {
+    const shareId = String(args.id || '');
+    if (!shareId)
+        return 'Required: id (memory ID to share).';
+    const force = Boolean(args.force);
+    // Pass tenantId so shareMemory's readEntry filters by tenant. Without
+    // this, a Bearer for tenant A could call hippo_share with tenant B's
+    // id and copy the row to the global store. The 'Memory not found'
+    // error matches the cross-tenant deny shape elsewhere in the code.
+    const shared = shareMemory(hippoRoot, shareId, { force, tenantId });
+    if (!shared)
+        return 'Transfer score too low. Use force=true to override.';
+    return `Shared [${shared.id}] to global store. Source: ${shared.source}`;
+}
+export function runPeersTool({ tenantId }) {
+    // D4 v1.12.10: tenant-scope the cross-project peer discovery.
+    // tenantId is the caller's tenant (matches hippo_share above);
+    // passing undefined would restore the pre-D4 host-wide behaviour.
+    const peers = listPeers(undefined, tenantId);
+    if (peers.length === 0)
+        return 'No peers found.';
+    return peers.map((p) => `${p.project}: ${p.count} memories (latest: ${p.latest.slice(0, 10)})`).join('\n');
+}
+//# sourceMappingURL=admin-tools.js.map

package/dist/mcp/format.d.ts

@@ -0,0 +1,27 @@
+import type { SearchResult } from '../search/types.js';
+import type { SessionEvent, TaskSnapshot } from '../store/rows.js';
+import type { ContextCost, ContinuityBlock, RecallResult, RecallResultItem } from '../api.js';
+import { type SessionHandoff } from '../handoff.js';
+import { detectAnchoring } from '../recall-history.js';
+import { detectAvailabilityBias } from '../availability.js';
+export declare function formatContinuityBlock(block: ContinuityBlock): string;
+export declare function formatMemories(results: ReadonlyArray<Pick<SearchResult, 'entry'>>): string;
+export interface RenderedRecall {
+    anchoring: ReturnType<typeof detectAnchoring>;
+    availability: ReturnType<typeof detectAvailabilityBias>;
+    text: string;
+    list: SearchResult[];
+}
+export interface RenderSlot {
+    rendered?: RenderedRecall;
+}
+/** What a memory costs the budget: the text formatMemories prints for it. */
+export declare const memoryCost: (r: Pick<SearchResult, "entry">) => number;
+export declare function memoriesReserve(budget: number): number;
+export declare function snapshotPiece(s: TaskSnapshot): string;
+export declare function handoffPiece(h: SessionHandoff): string;
+export declare function trailPiece(events: readonly SessionEvent[]): string;
+export declare const contextCost: ContextCost;
+export declare function tailSection(rows: RecallResultItem[]): string;
+export declare function planningSection(r: RecallResult): string;
+//# sourceMappingURL=format.d.ts.map