hippo-memory 1.60.0 → 1.61.0

package/dist/search/physics-search.js

@@ -0,0 +1,162 @@
+import { calculateStrength } from '../memory.js';
+import { estimateTokens } from '../token-ledger.js';
+import { evalNow, isRecallBoostAblated } from '../ablation.js';
+import { embeddingModelRequiresReindex } from '../embeddings.js';
+import { resolveEmbeddingProvider } from '../embedding-provider.js';
+import { physicsScore as computePhysicsScores, computeMass } from '../physics.js';
+import { DEFAULT_PHYSICS_CONFIG } from '../physics-config.js';
+import { loadPhysicsState } from '../physics-state.js';
+import { openHippoDb, closeHippoDb } from '../db.js';
+import { compareScoredResults } from '../compare.js';
+import { log } from '../log.js';
+import { churnStaleFactor, summaryMultipliers, summaryScoring } from './boosts.js';
+import { addDagFields, ageInDays } from './breakdown.js';
+import { fitBudget } from './finalize.js';
+import { hybridSearch } from './hybrid.js';
+import { currentEntries } from './as-of.js';
+import { vectorCandidatesOutside } from './vector.js';
+/** Scores memories by gravity, momentum and cluster amplification; rows without physics state rank through hybridSearch. */
+export async function physicsSearch(query, entries, options = {}) {
+    const now = options.now ?? evalNow(); // honors HIPPO_FAKE_NOW (eval-only; see ablation.ts)
+    const explain = options.explain ?? false;
+    const scoring = { now, explain, summary: summaryScoring(options) };
+    if (entries.length === 0 || !options.hippoRoot)
+        return [];
+    // memory_physics keeps only current positions and masses, so a past-dated query must rank without them.
+    if (options.asOf)
+        return hybridSearch(query, entries, options);
+    const root = options.hippoRoot;
+    const queryVector = await physicsQueryVector(query, root, options.queryEmbedding);
+    if (!queryVector)
+        return hybridSearch(query, entries, options);
+    const pool = currentEntries(withVectorCandidates(root, entries, queryVector, options.vectorCandidates), options);
+    const physicsMap = loadCandidateParticles(root, pool);
+    if (!physicsMap)
+        return hybridSearch(query, pool, options);
+    const pools = splitByParticle(pool, physicsMap, queryVector, now);
+    const config = options.physicsConfig ?? DEFAULT_PHYSICS_CONFIG;
+    const physicsResults = scorePhysicsPool(pools, queryVector, config, scoring);
+    const classicResults = pools.classic.length > 0
+        ? await hybridSearch(query, pools.classic, { ...options, vectorCandidates: undefined, budget: Infinity, explain })
+        : [];
+    const merged = mergeScorePools(physicsResults, classicResults);
+    merged.sort(compareScoredResults);
+    return fitBudget(merged, options.budget ?? 4000, options.minResults ?? 1, options.cost);
+}
+/** The caller's vector, else the provider's; null sends the caller to hybridSearch. */
+async function physicsQueryVector(query, root, given) {
+    if (given && given.length > 0)
+        return given;
+    // Physics scores against particle positions, not the stored vector index, so a pruned index must not block it.
+    try {
+        const provider = resolveEmbeddingProvider(root);
+        if (!provider.isAvailable() || embeddingModelRequiresReindex(root, provider.id))
+            return null;
+        const [vec] = await provider.embed([query], 'query');
+        return vec && vec.length > 0 ? vec : null;
+    }
+    catch (err) {
+        log.debug(`physics search: query embed failed, using hybrid: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+function withVectorCandidates(root, entries, queryVector, spec) {
+    if (!spec)
+        return entries;
+    try {
+        return [...entries, ...vectorCandidatesOutside(root, entries, queryVector, spec)];
+    }
+    catch (err) {
+        log.warn(`physics search ranked the lexical pool only; the vector lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+        return entries;
+    }
+}
+/** Particles for the candidate rows only, so one tenant's search never reads every tenant's physics state. */
+function loadCandidateParticles(root, pool) {
+    try {
+        const db = openHippoDb(root);
+        try {
+            return loadPhysicsState(db, pool.map((e) => e.id));
+        }
+        finally {
+            closeHippoDb(db);
+        }
+    }
+    catch (err) {
+        log.debug(`physics search: state load failed, using hybrid: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+function splitByParticle(pool, physicsMap, queryVector, now) {
+    const pools = { entries: [], particles: [], classic: [] };
+    for (const entry of pool) {
+        const particle = physicsMap.get(entry.id);
+        const usable = particle
+            && particle.position.length > 0
+            && particle.position.length === queryVector.length
+            && particle.velocity.length === queryVector.length;
+        if (!usable) {
+            pools.classic.push(entry);
+            continue;
+        }
+        pools.entries.push(entry);
+        // EVAL-ONLY ablation (see ablation.ts): persisted masses bake in recall history twice, so the flag recomputes mass live.
+        pools.particles.push(isRecallBoostAblated() ? { ...particle, mass: computeMass(calculateStrength(entry, now), entry.retrieval_count) } : particle);
+    }
+    return pools;
+}
+function scorePhysicsPool(pools, queryVector, config, scoring) {
+    if (pools.particles.length === 0)
+        return [];
+    const entryMap = new Map(pools.entries.map((e) => [e.id, e]));
+    // Content tie key: baseScore ties pick the cluster amplification set, so the order must hold across fresh ingests.
+    const scored = computePhysicsScores(pools.particles, queryVector, config, (id) => entryMap.get(id)?.content ?? id);
+    const results = [];
+    for (const s of scored) {
+        if (s.finalScore <= 0)
+            continue;
+        const entry = entryMap.get(s.memoryId);
+        if (!entry)
+            continue;
+        const summary = summaryMultipliers(entry, scoring.now, scoring.summary);
+        const churnStaleMultiplier = churnStaleFactor(entry);
+        const finalScore = s.finalScore * summary.deboost * summary.freshness * churnStaleMultiplier;
+        if (finalScore <= 0)
+            continue;
+        const result = { entry, score: finalScore, bm25: 0, cosine: s.baseScore, tokens: estimateTokens(entry.content) };
+        if (scoring.explain) {
+            result.breakdown = addDagFields(physicsBreakdown(entry, s.baseScore, finalScore, churnStaleMultiplier, scoring.now), entry, summary.deboost, summary.freshness);
+        }
+        results.push(result);
+    }
+    return results;
+}
+function physicsBreakdown(entry, baseScore, final, churnStaleMultiplier, now) {
+    return {
+        mode: 'physics',
+        normBm25: 0,
+        bm25Weight: 0,
+        embeddingWeight: 1,
+        cosine: baseScore,
+        base: baseScore,
+        strengthMultiplier: 1,
+        recencyMultiplier: 1,
+        decisionBoost: 1,
+        pathBoost: 1,
+        scopeBoost: 1,
+        sourceBump: 1,
+        outcomeBoost: 1,
+        churnStaleMultiplier,
+        matchedTerms: [],
+        final,
+        ageDays: ageInDays(entry, now),
+    };
+}
+/** Normalizes each pool to [0, 1] by its largest pre-churn score, then concatenates them. */
+function mergeScorePools(poolA, poolB) {
+    const unpenalised = (r) => r.score / churnStaleFactor(r.entry);
+    const maxA = poolA.reduce((m, r) => Math.max(m, unpenalised(r)), 1e-9);
+    const maxB = poolB.reduce((m, r) => Math.max(m, unpenalised(r)), 1e-9);
+    return [...poolA.map((r) => ({ ...r, score: r.score / maxA })), ...poolB.map((r) => ({ ...r, score: r.score / maxB }))];
+}
+//# sourceMappingURL=physics-search.js.map

package/dist/search/rerank.d.ts

@@ -0,0 +1,10 @@
+import type { RerankerFn, RerankerOptions } from '../rerankers/types.js';
+import type { SearchResult } from './types.js';
+/** MMR: repeatedly picks the candidate maximising lambda * relevance - (1 - lambda) * max(cos(cand, picked)).
+ *  Input must be sorted by relevance; strict `>` keeps ties first-wins, so a deterministic input stays deterministic. */
+export declare function mmrRerank(scored: SearchResult[], embeddingIndex: Record<string, number[]>, lambda: number, explain: boolean): SearchResult[];
+/** MMR over the top window only; the tail keeps its relevance order. */
+export declare function applyMmrWindow(scored: SearchResult[], embeddingIndex: Record<string, number[]>, lambda: number, explain: boolean): SearchResult[];
+/** Runs the reranker over the top `topK` (default 50) and stamps pre and post ranks; see src/rerankers/types.ts. */
+export declare function applyReranker(query: string, ordered: SearchResult[], reranker: RerankerFn, rerankerOptions?: RerankerOptions): Promise<SearchResult[]>;
+//# sourceMappingURL=rerank.d.ts.map

package/dist/search/rerank.js

@@ -0,0 +1,72 @@
+import { cosineSimilarity } from '../embeddings.js';
+// MMR is O(K^2) cosine ops; candidates below this window never survive budget filtering anyway.
+const MMR_CANDIDATE_CAP = 100;
+/** MMR: repeatedly picks the candidate maximising lambda * relevance - (1 - lambda) * max(cos(cand, picked)).
+ *  Input must be sorted by relevance; strict `>` keeps ties first-wins, so a deterministic input stays deterministic. */
+export function mmrRerank(scored, embeddingIndex, lambda, explain) {
+    if (scored.length === 0)
+        return scored;
+    const maxScore = scored[0].score || 1;
+    const normScore = scored.map((r) => r.score / maxScore);
+    const vectors = scored.map((r) => embeddingIndex[r.entry.id] ?? null);
+    const picked = [];
+    const remaining = new Set(scored.map((_, i) => i));
+    while (remaining.size > 0) {
+        let bestIdx = -1;
+        let bestMmr = -Infinity;
+        for (const i of remaining) {
+            const maxSim = maxSimilarityToPicked(vectors[i], picked, embeddingIndex);
+            const mmr = lambda * normScore[i] - (1 - lambda) * maxSim;
+            if (mmr > bestMmr) {
+                bestMmr = mmr;
+                bestIdx = i;
+            }
+        }
+        if (bestIdx === -1)
+            break;
+        remaining.delete(bestIdx);
+        picked.push(scored[bestIdx]);
+    }
+    if (explain)
+        attachMmrRanks(scored, picked);
+    return picked;
+}
+function maxSimilarityToPicked(vi, picked, embeddingIndex) {
+    let maxSim = 0;
+    if (!vi)
+        return maxSim;
+    for (const p of picked) {
+        const vp = embeddingIndex[p.entry.id];
+        if (!vp || vp.length !== vi.length)
+            continue;
+        const sim = Math.max(0, cosineSimilarity(vi, vp));
+        if (sim > maxSim)
+            maxSim = sim;
+    }
+    return maxSim;
+}
+function attachMmrRanks(scored, picked) {
+    const preRank = new Map();
+    scored.forEach((r, i) => preRank.set(r.entry.id, i + 1));
+    picked.forEach((r, i) => {
+        if (r.breakdown) {
+            r.breakdown.preMmrRank = preRank.get(r.entry.id);
+            r.breakdown.postMmrRank = i + 1;
+        }
+    });
+}
+/** MMR over the top window only; the tail keeps its relevance order. */
+export function applyMmrWindow(scored, embeddingIndex, lambda, explain) {
+    const head = scored.slice(0, MMR_CANDIDATE_CAP);
+    const tail = scored.slice(MMR_CANDIDATE_CAP);
+    return [...mmrRerank(head, embeddingIndex, lambda, explain), ...tail];
+}
+/** Runs the reranker over the top `topK` (default 50) and stamps pre and post ranks; see src/rerankers/types.ts. */
+export async function applyReranker(query, ordered, reranker, rerankerOptions) {
+    const topK = rerankerOptions?.topK ?? 50;
+    const head = ordered.slice(0, topK).map((r, i) => ({ ...r, preRerankRank: i + 1 }));
+    const tail = ordered.slice(topK);
+    const reranked = await reranker(query, head, { ...rerankerOptions, topK });
+    return [...reranked.map((r, i) => ({ ...r, postRerankRank: i + 1 })), ...tail];
+}
+//# sourceMappingURL=rerank.js.map

package/dist/search/temporal.d.ts

@@ -0,0 +1,15 @@
+import type { MemoryEntry } from '../memory.js';
+export type TemporalDirection = 'recent' | 'oldest' | null;
+export declare function detectTemporalDirection(query: string): TemporalDirection;
+export interface TemporalRange {
+    minTime: number;
+    maxTime: number;
+}
+export declare function computeTemporalRange(entries: MemoryEntry[]): TemporalRange;
+export declare function temporalBoost(entry: MemoryEntry, direction: TemporalDirection, range: TemporalRange): number;
+/** The query's temporal cue and, only when there is one, the pool's time range. */
+export declare function temporalContext(query: string, entries: MemoryEntry[]): {
+    direction: TemporalDirection;
+    range: TemporalRange;
+};
+//# sourceMappingURL=temporal.d.ts.map

package/dist/search/temporal.js

@@ -0,0 +1,45 @@
+const TEMPORAL_RECENT_CUES = new Set(['recently', 'latest', 'last', 'newest', 'current', 'today']);
+const TEMPORAL_OLDEST_CUES = new Set(['first', 'earliest', 'oldest', 'initially', 'originally']);
+export function detectTemporalDirection(query) {
+    const words = query.toLowerCase().split(/\s+/);
+    for (const w of words) {
+        if (TEMPORAL_RECENT_CUES.has(w))
+            return 'recent';
+        if (TEMPORAL_OLDEST_CUES.has(w))
+            return 'oldest';
+    }
+    return null;
+}
+export function computeTemporalRange(entries) {
+    let minTime = Infinity;
+    let maxTime = -Infinity;
+    for (const e of entries) {
+        const t = new Date(e.created).getTime();
+        if (t < minTime)
+            minTime = t;
+        if (t > maxTime)
+            maxTime = t;
+    }
+    return { minTime, maxTime };
+}
+export function temporalBoost(entry, direction, range) {
+    if (!direction)
+        return 1.0;
+    const span = range.maxTime - range.minTime;
+    if (span === 0)
+        return 1.0;
+    const entryTime = new Date(entry.created).getTime();
+    const normalized = (entryTime - range.minTime) / span;
+    if (direction === 'recent') {
+        return 0.8 + 0.4 * normalized;
+    }
+    else {
+        return 0.8 + 0.4 * (1 - normalized);
+    }
+}
+/** The query's temporal cue and, only when there is one, the pool's time range. */
+export function temporalContext(query, entries) {
+    const direction = detectTemporalDirection(query);
+    return { direction, range: direction ? computeTemporalRange(entries) : { minTime: 0, maxTime: 0 } };
+}
+//# sourceMappingURL=temporal.js.map

package/dist/search/types.d.ts

@@ -0,0 +1,91 @@
+import type { MemoryEntry } from '../memory.js';
+/** One score mutation applied after candidate generation; allocated only under `recall --why` or `RecallOpts.explain`. */
+export interface RerankStep {
+    /** One of: interference, value, utility, reranker, goal-boost, retrieval-count-downweight. */
+    stage: string;
+    /** The score multiplier applied at this stage, when the transform is a scalar multiply. */
+    multiplier?: number;
+    /** Score before this stage ran. */
+    scoreBefore: number;
+    /** Score after this stage ran. */
+    scoreAfter: number;
+    /** Optional human-readable detail (e.g. the matched goal tags). */
+    note?: string;
+}
+export interface SearchResult {
+    entry: MemoryEntry;
+    score: number;
+    bm25: number;
+    cosine: number;
+    tokens: number;
+    /** Populated when search is called with options.explain === true. */
+    breakdown?: ScoreBreakdown;
+    /** Ordered lifecycle re-ranking steps that mutated `score`; set only when `recall --why` asks for it. */
+    rerankTrace?: RerankStep[];
+    /** Set when a reranker ran; orders the results while `score` keeps the pre-rerank value. */
+    rerankScore?: number;
+    preRerankRank?: number;
+    postRerankRank?: number;
+    /** Set for results reached by graph traversal (`recall --hops N`): how the memory was reached from a lexical seed. */
+    graphVia?: {
+        hops: number;
+        relType: string;
+        direction: 'from' | 'to';
+    };
+}
+/** What a result costs against a budget: the tokens of the text it prints as. */
+export type ResultCost = (r: SearchResult) => number;
+export interface ScoreBreakdown {
+    /** `hybrid`: BM25 plus a cached doc vector; `hybrid-no-vec`: the query was embedded but this doc has no vector
+     *  (run `hippo embed`); `bm25-only`: no usable embeddings; `physics`: scored by the physics engine. */
+    mode: 'hybrid' | 'hybrid-no-vec' | 'bm25-only' | 'physics';
+    /** BM25 score after normalization by max-in-corpus (0..1). */
+    normBm25: number;
+    /** Weight applied to BM25 in the hybrid blend. */
+    bm25Weight: number;
+    /** Weight applied to cosine in the hybrid blend. */
+    embeddingWeight: number;
+    /** Cosine similarity (0 when embeddings not used). */
+    cosine: number;
+    /** Blended base score before multipliers. */
+    base: number;
+    /** Multiplier from memory strength: 0.5 + 0.5*strength. */
+    strengthMultiplier: number;
+    /** Multiplier from age: 0.8 + 0.2*recencyBoost. */
+    recencyMultiplier: number;
+    /** 1.2 if tagged 'decision', else 1.0. */
+    decisionBoost: number;
+    /** 1.0..1.3 based on cwd path tag overlap. */
+    pathBoost: number;
+    /** 1.5 if scope matches, 0.5 if scope mismatches, 1.0 if neutral. */
+    scopeBoost: number;
+    /** Extra multiplier applied post-hybrid (e.g. 1.2x for local hits in a local+global merge); 1.0 otherwise. */
+    sourceBump: number;
+    /** Immediate outcome nudge, 1 + 0.15*tanh(pos - neg) clipped to [0.85, 1.15]; separate from the slow strength path. */
+    outcomeBoost: number;
+    /** CHURN_STALE_RANK_MULTIPLIER if tagged 'churn-stale', else 1.0. */
+    churnStaleMultiplier: number;
+    /** Pre-MMR rank (1-indexed). Only set when MMR re-ranking ran. */
+    preMmrRank?: number;
+    /** Post-MMR rank (1-indexed). Only set when MMR re-ranking ran. */
+    postMmrRank?: number;
+    /** Query terms that appeared verbatim in the doc. */
+    matchedTerms: string[];
+    /** Final composite score (= base * multipliers). */
+    final: number;
+    /** Age of the memory in whole days, at scoring time. */
+    ageDays: number;
+    /** entry.dag_level (0=raw, 1=extracted, 2=topic, 3=entity). */
+    dagLevel?: number;
+    /** descendant_count column, refreshed by the DAG rebuild. */
+    descendantCount?: number;
+    /** last_rebuilt_at ISO; null if never rebuilt. Summaries only. */
+    lastRebuiltAt?: string | null;
+    /** Cumulative rebuild_count. Summaries only. */
+    rebuildCount?: number;
+    /** Deboost applied (1.0 for non-summaries; default 0.85 for summaries). */
+    summaryDeboost?: number;
+    /** 1.05 if a summary was rebuilt within 7 days; 1.0 otherwise. */
+    summaryFreshnessBoost?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/search/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/search/vector.d.ts

@@ -0,0 +1,30 @@
+import type { MemoryEntry } from '../memory.js';
+import { type VectorCandidateSpec } from '../store/search-rows.js';
+import { type CurrentnessOptions } from './as-of.js';
+/** hybridSearch's vector arm: which rows it may add, plus the caller's JS admission rules (exact private regex, entry filters). */
+export type HybridVectorCandidates = VectorCandidateSpec & {
+    admit?: (entry: MemoryEntry) => boolean;
+};
+/** What the vector arm produced; fields fill in step by step, so a late failure keeps the rows already added. */
+export interface VectorArm {
+    entries: MemoryEntry[];
+    addedRows: boolean;
+    useEmbeddings: boolean;
+    embeddingIndex: Record<string, number[]>;
+    queryVector: number[];
+}
+export interface VectorArmOptions extends CurrentnessOptions {
+    hippoRoot?: string;
+    vectorCandidates?: HybridVectorCandidates;
+}
+/** The nearest admitted rows not already in `entries`. */
+export declare function vectorCandidatesOutside(hippoRoot: string, entries: readonly MemoryEntry[], queryVector: readonly number[], spec: HybridVectorCandidates): MemoryEntry[];
+/** Embeds the query and loads stored vectors; any failure leaves BM25 to rank alone. */
+export declare function resolveVectorArm(query: string, entries: MemoryEntry[], options: VectorArmOptions): Promise<VectorArm>;
+export interface DenseScores {
+    cosine: number[];
+    /** Whether each entry had a cached doc vector to compare against. */
+    hadVec: boolean[];
+}
+export declare function denseScores(arm: VectorArm): DenseScores;
+//# sourceMappingURL=vector.d.ts.map

package/dist/search/vector.js

@@ -0,0 +1,71 @@
+import { cosineSimilarity, embeddingModelRequiresReindex, hasEmbeddings, loadStoredVectors } from '../embeddings.js';
+import { loadVectorCandidateEntries } from '../store/search-rows.js';
+import { resolveEmbeddingProvider } from '../embedding-provider.js';
+import { log } from '../log.js';
+import { redactSecretsStrict } from '../secret-detect.js';
+import { currentEntries } from './as-of.js';
+// Search runs on every hook prompt, so one line per reason per process says why vectors went unused without flooding stderr.
+function warnBm25Fallback(reason, detail) {
+    log.once(`search.bm25-fallback.${reason}`, 'warn', `hybrid search fell back to BM25 only: ${redactSecretsStrict(detail)}`);
+}
+/** The nearest admitted rows not already in `entries`. */
+export function vectorCandidatesOutside(hippoRoot, entries, queryVector, spec) {
+    const inPool = new Set(entries.map((e) => e.id));
+    return loadVectorCandidateEntries(hippoRoot, queryVector, spec).filter((e) => !inPool.has(e.id) && (spec.admit?.(e) ?? true));
+}
+/** Embeds the query and loads stored vectors; any failure leaves BM25 to rank alone. */
+export async function resolveVectorArm(query, entries, options) {
+    const arm = { entries, addedRows: false, useEmbeddings: false, embeddingIndex: {}, queryVector: [] };
+    if (!options.hippoRoot)
+        return arm;
+    try {
+        await fillVectorArm(arm, query, options.hippoRoot, options);
+    }
+    catch (err) {
+        warnBm25Fallback('error', err instanceof Error ? err.message : String(err));
+    }
+    return arm;
+}
+async function fillVectorArm(arm, query, root, options) {
+    const provider = resolveEmbeddingProvider(root);
+    if (!provider.isAvailable())
+        return;
+    if (embeddingModelRequiresReindex(root, provider.id)) {
+        warnBm25Fallback('reindex', "the embedding index was built by another model or is being rebuilt; run 'hippo embed'");
+        return;
+    }
+    const spec = options.vectorCandidates;
+    const vectors = loadStoredVectors(root, arm.entries.map((e) => e.id));
+    // Only spend a (possibly paid, off-box) query embedding when there is a stored vector this search can use.
+    if (vectors.size === 0 && !(spec !== undefined && hasEmbeddings(root)))
+        return;
+    const [vec] = await provider.embed([query], 'query');
+    arm.queryVector = vec ?? [];
+    if (arm.queryVector.length === 0) {
+        warnBm25Fallback('empty-query-vector', 'the embedding provider returned no vector for the query');
+        return;
+    }
+    const added = spec ? vectorCandidatesOutside(root, arm.entries, arm.queryVector, spec) : [];
+    if (added.length > 0) {
+        arm.addedRows = true;
+        arm.entries = currentEntries([...arm.entries, ...added], options);
+        for (const [id, v] of loadStoredVectors(root, added.map((e) => e.id)))
+            vectors.set(id, v);
+    }
+    arm.embeddingIndex = Object.fromEntries(vectors);
+    arm.useEmbeddings = true;
+}
+export function denseScores(arm) {
+    const n = arm.entries.length;
+    const cosine = new Array(n).fill(0);
+    const hadVec = new Array(n).fill(false);
+    if (!arm.useEmbeddings)
+        return { cosine, hadVec };
+    for (let i = 0; i < n; i++) {
+        const cached = arm.embeddingIndex[arm.entries[i].id];
+        hadVec[i] = Boolean(cached && arm.queryVector.length > 0);
+        cosine[i] = hadVec[i] ? Math.max(0, cosineSimilarity(arm.queryVector, cached)) : 0;
+    }
+    return { cosine, hadVec };
+}
+//# sourceMappingURL=vector.js.map

package/dist/secret-detect.d.ts

@@ -23,6 +23,8 @@ export interface SecretDetection {
     flagged: boolean;
     reason: string | null;
 }
+/** Tags that flag a memory as secret, lower case; detectSecret folds a tag's case before the lookup. */
+export declare const SECRET_TAGS: ReadonlySet<string>;
 /**
  * Scan a memory's tags + content for secret material.
  * Pure and deterministic; no filesystem or store access.

package/dist/secret-detect.js

@@ -18,7 +18,8 @@
  * Leaf module: keep free of imports from store/api/shared so all of them
  * can import it without cycles.
  */
-const SECRET_TAGS = new Set([
+/** Tags that flag a memory as secret, lower case; detectSecret folds a tag's case before the lookup. */
+export const SECRET_TAGS = new Set([
     'secret', 'api-key', 'apikey', 'credential', 'credentials',
     'token', 'password', 'private-key',
 ]);

package/dist/server/auth.d.ts

@@ -0,0 +1,52 @@
+import type { IncomingMessage } from 'node:http';
+import type { Context } from '../api.js';
+import type { ServeOpts } from './types.js';
+/**
+ * Recognise loopback remote addresses. Node reports IPv6-mapped IPv4 as
+ * '::ffff:127.0.0.1' on dual-stack sockets, so we accept that alongside
+ * the bare v4 and v6 loopbacks. Anything else is treated as remote.
+ */
+export declare function isLoopback(remoteAddress: string | undefined): boolean;
+/**
+ * Read the Authorization header in a case-insensitive way and pull the
+ * bearer token out. Returns:
+ *   - { kind: 'absent' } when no Authorization header is present
+ *   - { kind: 'malformed' } when the header is set but not 'Bearer <token>'
+ *   - { kind: 'bearer', token } when a non-empty bearer token is present
+ *
+ * The header NAME is case-insensitive (Node lowercases all header names on
+ * IncomingMessage.headers); the SCHEME ('Bearer') is also matched
+ * case-insensitively per RFC 6750.
+ */
+type AuthHeader = {
+    kind: 'absent';
+} | {
+    kind: 'malformed';
+} | {
+    kind: 'bearer';
+    token: string;
+};
+export declare function readAuthHeader(req: IncomingMessage): AuthHeader;
+type AuthOpts = Pick<ServeOpts, 'hippoRoot' | 'authResolver' | 'authResolverTimeoutMs'>;
+/** Add-ons call this to refuse a subject that would collide with a built-in actor. */
+export declare function isReservedActor(subject: string): boolean;
+/**
+ * Build a per-request Context from the Authorization header and remote
+ * address. Throws HttpError(401) for invalid / missing credentials. Opens
+ * the DB only for an API-key-shaped Bearer token (or any Bearer token when no
+ * auth resolver is registered), so loopback no-auth requests stay cheap.
+ */
+export declare function buildContextWithAuth(req: IncomingMessage, opts: AuthOpts): Promise<Context>;
+/**
+ * Auth check for routes that do not need a tenant Context (e.g. MCP transport,
+ * which builds its own root resolution via findHippoRoot). Throws HttpError
+ * 401 the same way buildContextWithAuth does, but skips building the Context
+ * envelope. Loopback no-auth still passes.
+ */
+export declare function requireAuth(req: IncomingMessage, opts: AuthOpts): Promise<void>;
+/** Never rejects: an outage (5xx) skips one heartbeat tick, only a definite 4xx denial closes the stream. */
+export declare function heartbeatVerdict(req: IncomingMessage, opts: AuthOpts): Promise<'ok' | 'revoked' | 'unavailable'>;
+/** Gate for any action beyond the caller's own tenant: a tenant's admin, by key or resolver, is never a host admin. */
+export declare function assertCrossTenantAdmin(ctx: Context, what: string): void;
+export {};
+//# sourceMappingURL=auth.d.ts.map