peon-mem 1.0.0

package/dist/quality.js

@@ -0,0 +1,338 @@
+export function deduplicateMemoryRecords(records) {
+    const entries = [];
+    const keyToIndex = new Map();
+    const duplicates = [];
+    for (const record of records) {
+        const key = memoryKey(record);
+        const existingIndex = keyToIndex.get(key);
+        if (existingIndex === undefined) {
+            keyToIndex.set(key, entries.length);
+            entries.push({ key, record: cloneRecord(record) });
+            continue;
+        }
+        const current = entries[existingIndex].record;
+        const keepIncoming = memoryStrength(record) > memoryStrength(current);
+        const kept = keepIncoming ? mergeDuplicate(record, current) : mergeDuplicate(current, record);
+        entries[existingIndex] = { key, record: kept };
+        duplicates.push({
+            duplicateId: keepIncoming ? current.id : record.id,
+            keptId: kept.id,
+            key
+        });
+    }
+    return {
+        records: entries.map((entry) => entry.record),
+        duplicates
+    };
+}
+export function detectMemoryConflicts(records) {
+    const conflicts = [];
+    for (let leftIndex = 0; leftIndex < records.length; leftIndex += 1) {
+        for (let rightIndex = leftIndex + 1; rightIndex < records.length; rightIndex += 1) {
+            const left = records[leftIndex];
+            const right = records[rightIndex];
+            const entity = sharedEntity(left, right);
+            if (!entity)
+                continue;
+            const reason = opposingLanguageReason(left.content, right.content);
+            if (!reason)
+                continue;
+            conflicts.push({
+                entity,
+                leftId: left.id,
+                rightId: right.id,
+                reason
+            });
+        }
+    }
+    return conflicts;
+}
+export function markStaleMemoryRecords(records, options = {}) {
+    const now = options.now ?? new Date();
+    const staleAfterDays = options.staleAfterDays ?? 120;
+    const staleIds = [];
+    return {
+        records: records.map((record) => {
+            if (record.status !== "active")
+                return cloneRecord(record);
+            if (ageInDays(record.updatedAt, now) <= staleAfterDays)
+                return cloneRecord(record);
+            staleIds.push(record.id);
+            return {
+                ...cloneRecord(record),
+                status: "stale"
+            };
+        }),
+        staleIds
+    };
+}
+export function promoteMemoryRecords(records, options = {}) {
+    const repeatThreshold = options.repeatThreshold ?? 2;
+    const repeatBoost = options.repeatBoost ?? 0.2;
+    const importantBoost = options.importantBoost ?? 0.15;
+    const repeatedCounts = countNormalized(options.repeatedContent ?? []);
+    const importantTerms = (options.importantTerms ?? []).map(normalizeMemory).filter(Boolean);
+    const promoted = [];
+    const promotedRecords = records.map((record) => {
+        const normalized = normalizeMemory(record.content);
+        const isRepeated = (repeatedCounts.get(normalized) ?? 0) >= repeatThreshold;
+        const isImportant = importantTerms.some((term) => normalized.includes(term));
+        const boost = (isRepeated ? repeatBoost : 0) + (isImportant ? importantBoost : 0);
+        if (boost <= 0)
+            return cloneRecord(record);
+        const importance = clamp(record.score.importance + boost);
+        if (importance === record.score.importance)
+            return cloneRecord(record);
+        promoted.push({
+            id: record.id,
+            reason: isRepeated ? "repeated" : "important",
+            importance
+        });
+        return {
+            ...cloneRecord(record),
+            score: {
+                ...record.score,
+                importance
+            }
+        };
+    });
+    return { records: promotedRecords, promoted };
+}
+export function applyMemoryQualityReport(records, report) {
+    return {
+        records: report.records.map(cloneRecord),
+        audit: summarizeMemoryQualityReport(report, records)
+    };
+}
+export function summarizeMemoryQualityReport(report, records) {
+    const removedIds = uniquePreservingOrder(report.duplicates.map((duplicate) => duplicate.duplicateId));
+    const updatedIds = [];
+    const retainedIds = [];
+    if (records) {
+        const finalById = new Map(report.records.map((record) => [record.id, record]));
+        for (const record of records) {
+            const finalRecord = finalById.get(record.id);
+            if (!finalRecord) {
+                if (!removedIds.includes(record.id))
+                    removedIds.push(record.id);
+                continue;
+            }
+            if (sameJsonSafeRecord(record, finalRecord)) {
+                retainedIds.push(record.id);
+            }
+            else {
+                updatedIds.push(record.id);
+            }
+        }
+    }
+    else {
+        const changedIds = new Set();
+        for (const id of report.staleIds)
+            changedIds.add(id);
+        for (const id of report.promotedIds)
+            changedIds.add(id);
+        for (const conflict of report.conflicts) {
+            changedIds.add(conflict.leftId);
+            changedIds.add(conflict.rightId);
+        }
+        for (const record of report.records) {
+            if (changedIds.has(record.id)) {
+                updatedIds.push(record.id);
+            }
+            else {
+                retainedIds.push(record.id);
+            }
+        }
+    }
+    return {
+        inputCount: report.inputCount,
+        outputCount: report.outputCount,
+        removedDuplicateCount: report.duplicates.length,
+        conflictCount: report.conflicts.length,
+        staleCount: report.staleIds.length,
+        promotedCount: report.promotedIds.length,
+        changedCount: updatedIds.length,
+        unchangedCount: retainedIds.length,
+        removedIds,
+        updatedIds,
+        retainedIds
+    };
+}
+export function serializeMemoryQualityReport(report) {
+    return {
+        inputCount: safeInteger(report.inputCount),
+        outputCount: safeInteger(report.outputCount),
+        records: report.records.map(jsonSafeRecord),
+        duplicates: report.duplicates.map((duplicate) => ({
+            duplicateId: String(duplicate.duplicateId),
+            keptId: String(duplicate.keptId),
+            key: String(duplicate.key)
+        })),
+        conflicts: report.conflicts.map((conflict) => ({
+            entity: String(conflict.entity),
+            leftId: String(conflict.leftId),
+            rightId: String(conflict.rightId),
+            reason: String(conflict.reason)
+        })),
+        staleIds: report.staleIds.map(String),
+        promotedIds: report.promotedIds.map(String),
+        audit: summarizeMemoryQualityReport(report)
+    };
+}
+export function createQualityReport(records, options = {}) {
+    const deduplicated = deduplicateMemoryRecords(records);
+    const stale = markStaleMemoryRecords(deduplicated.records, options);
+    const promoted = promoteMemoryRecords(stale.records, options);
+    // Superseded records are a settled verdict (a belief was explicitly replaced);
+    // never re-flag them as "conflicted" — that would clobber the supersede link.
+    const conflicts = detectMemoryConflicts(promoted.records.filter((record) => record.status !== "superseded"));
+    const conflictedIds = new Set(conflicts.flatMap((conflict) => [conflict.leftId, conflict.rightId]));
+    const finalRecords = promoted.records.map((record) => conflictedIds.has(record.id)
+        ? {
+            ...cloneRecord(record),
+            status: "conflicted"
+        }
+        : cloneRecord(record));
+    return {
+        inputCount: records.length,
+        outputCount: finalRecords.length,
+        records: finalRecords,
+        duplicates: deduplicated.duplicates,
+        conflicts,
+        staleIds: stale.staleIds,
+        promotedIds: promoted.promoted.map((record) => record.id)
+    };
+}
+function memoryKey(record) {
+    return `${record.type}:${normalizeMemory(record.content)}`;
+}
+function mergeDuplicate(kept, duplicate) {
+    return {
+        ...cloneRecord(kept),
+        score: {
+            importance: clamp(Math.max(kept.score.importance, duplicate.score.importance)),
+            confidence: clamp(Math.max(kept.score.confidence, duplicate.score.confidence))
+        },
+        entities: uniqueSorted([...kept.entities, ...duplicate.entities])
+    };
+}
+function memoryStrength(record) {
+    return record.score.importance + record.score.confidence + epochMillis(record.updatedAt) / 1_000_000_000_000_000;
+}
+function sharedEntity(left, right) {
+    const rightEntities = new Map(right.entities.map((entity) => [normalizeEntity(entity), entity]));
+    for (const leftEntity of left.entities) {
+        const match = rightEntities.get(normalizeEntity(leftEntity));
+        if (match)
+            return leftEntity.trim() || match;
+    }
+    return undefined;
+}
+function opposingLanguageReason(left, right) {
+    const leftText = normalizeMemory(left);
+    const rightText = normalizeMemory(right);
+    const pairs = [
+        ["enabled", "disabled", "opposing enabled/disabled language"],
+        ["enable", "disable", "opposing enable/disable language"],
+        ["allowed", "forbidden", "opposing allowed/forbidden language"],
+        ["allow", "deny", "opposing allow/deny language"],
+        ["required", "optional", "opposing required/optional language"],
+        ["true", "false", "opposing true/false language"],
+        ["yes", "no", "opposing yes/no language"],
+        ["use", "avoid", "opposing use/avoid language"]
+    ];
+    for (const [positive, negative, reason] of pairs) {
+        if (hasWord(leftText, positive) && hasWord(rightText, negative))
+            return reason;
+        if (hasWord(leftText, negative) && hasWord(rightText, positive))
+            return reason;
+    }
+    return undefined;
+}
+function ageInDays(value, now) {
+    const updatedAt = epochMillis(value);
+    if (!Number.isFinite(updatedAt))
+        return 0;
+    return (now.getTime() - updatedAt) / 86_400_000;
+}
+function epochMillis(value) {
+    const timestamp = Date.parse(value);
+    return Number.isFinite(timestamp) ? timestamp : 0;
+}
+function countNormalized(values) {
+    const counts = new Map();
+    for (const value of values) {
+        const normalized = normalizeMemory(value);
+        if (!normalized)
+            continue;
+        counts.set(normalized, (counts.get(normalized) ?? 0) + 1);
+    }
+    return counts;
+}
+function normalizeMemory(content) {
+    return content
+        .toLowerCase()
+        .replace(/[`"'.,;:!?()[\]{}]/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function normalizeEntity(entity) {
+    return normalizeMemory(entity);
+}
+function hasWord(content, word) {
+    return new RegExp(`(^|\\s)${escapeRegExp(word)}($|\\s)`).test(content);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function uniqueSorted(values) {
+    return Array.from(new Set(values.map((value) => value.trim()).filter(Boolean))).sort((left, right) => left.localeCompare(right));
+}
+function uniquePreservingOrder(values) {
+    const seen = new Set();
+    return values.filter((value) => {
+        if (seen.has(value))
+            return false;
+        seen.add(value);
+        return true;
+    });
+}
+function cloneRecord(record) {
+    return {
+        ...record,
+        score: { ...record.score },
+        source: { ...record.source },
+        entities: [...record.entities]
+    };
+}
+function clamp(value) {
+    return Math.max(0, Math.min(1, Number.isFinite(value) ? value : 0));
+}
+function safeInteger(value) {
+    return Number.isSafeInteger(value) ? value : 0;
+}
+function sameJsonSafeRecord(left, right) {
+    return JSON.stringify(jsonSafeRecord(left)) === JSON.stringify(jsonSafeRecord(right));
+}
+function jsonSafeRecord(record) {
+    return {
+        id: String(record.id),
+        type: record.type,
+        content: String(record.content),
+        normalized: String(record.normalized),
+        scope: record.scope,
+        status: record.status,
+        score: {
+            importance: clamp(record.score.importance),
+            confidence: clamp(record.score.confidence)
+        },
+        source: {
+            kind: record.source.kind,
+            ...(record.source.reason === undefined ? {} : { reason: String(record.source.reason) })
+        },
+        entities: record.entities.map(String),
+        createdAt: String(record.createdAt),
+        updatedAt: String(record.updatedAt),
+        ...(record.supersededBy === undefined ? {} : { supersededBy: String(record.supersededBy) })
+    };
+}

package/dist/recuration.d.ts

@@ -0,0 +1,13 @@
+import type { PeonConfig } from "./config.js";
+import type { MemoryRecord } from "./types.js";
+/**
+ * One-time cleanup: re-judge a project's EXISTING beliefs against the sharpened
+ * rules and return the ids to retire. Operates on already-distilled beliefs (not
+ * raw events) so it's cheap, preserves supersession history, and only removes the
+ * ephemeral/trivial/duplicate noise the old prompt let through. Removed beliefs are
+ * archived (recoverable), never deleted.
+ */
+export type Recurator = (records: readonly MemoryRecord[]) => Promise<string[]>;
+export declare function createRecurator(config: PeonConfig): Recurator | null;
+/** Tolerant parse of the model's id list. */
+export declare function parseIdArray(content: string): string[];

package/dist/recuration.js

@@ -0,0 +1,65 @@
+const BATCH_SIZE = 30;
+const PER_BATCH_MAX_FRACTION = 0.4; // a batch that wants to drop more than this is misjudging — skip it
+export function createRecurator(config) {
+    if (config.aiMode === "off" || !config.openRouterApiKey)
+        return null;
+    return async (records) => {
+        const active = records.filter((r) => r.status === "active" && !r.pinned);
+        if (active.length === 0)
+            return [];
+        // Judge in small batches — the model reasons reliably over ~30 beliefs but
+        // over-selects wildly when handed hundreds at once.
+        const drop = [];
+        for (let i = 0; i < active.length; i += BATCH_SIZE) {
+            const batch = active.slice(i, i + BATCH_SIZE);
+            const ids = await judgeBatch(config, batch).catch(() => []);
+            const valid = ids.filter((id) => batch.some((r) => r.id === id));
+            // Per-batch rogue guard: if a batch wants to drop most of itself, skip it entirely.
+            if (valid.length > Math.max(3, Math.floor(batch.length * PER_BATCH_MAX_FRACTION)))
+                continue;
+            drop.push(...valid);
+        }
+        return drop;
+    };
+}
+async function judgeBatch(config, batch) {
+    const list = batch.map((r) => `${r.id} | ${r.type} | ${r.content}`).join("\n");
+    const system = "You are CONSERVATIVELY trimming a project's memory. Each line is 'id | type | content'. " +
+        "Default action is KEEP. Remove a belief ONLY if it is unmistakably one of: " +
+        "(a) an ephemeral one-time ACTION with no lasting meaning — 'cloned the repo', 'installed deps', 'created a directory', " +
+        "'downloaded weights', 'submitted/monitored a job', 'confirmed the job is pending', 'added a warning filter'; OR " +
+        "(b) an EXACT duplicate of another belief in the list (keep one, remove the literal repeats). " +
+        "Do NOT remove anything for being merely 'less important', verbose, or arguable — only clear noise and exact dupes. " +
+        "KEEP every decision, result/metric, preference, file, and open question unless it is pure setup-action noise. " +
+        "You should typically remove only a small fraction; removing most beliefs is WRONG. When in any doubt, KEEP. " +
+        "Output ONLY a JSON array of the ids to remove — no fences, no prose. If none, return [].";
+    const response = await fetch("https://openrouter.ai/api/v1/chat/completions", {
+        method: "POST",
+        headers: { Authorization: `Bearer ${config.openRouterApiKey}`, "Content-Type": "application/json" },
+        body: JSON.stringify({
+            model: config.processingModel,
+            messages: [
+                { role: "system", content: system },
+                { role: "user", content: `Beliefs:\n${list}\n\nIds to remove (JSON array):` }
+            ],
+            temperature: 0.1
+        })
+    });
+    if (!response.ok)
+        throw new Error(`recuration failed with ${response.status}`);
+    const json = (await response.json());
+    return parseIdArray(json.choices?.[0]?.message?.content ?? "");
+}
+/** Tolerant parse of the model's id list. */
+export function parseIdArray(content) {
+    const text = content.trim();
+    const fenced = text.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+    const body = fenced ? fenced[1] : text.slice(text.indexOf("["), text.lastIndexOf("]") + 1);
+    try {
+        const parsed = JSON.parse(body || text);
+        return Array.isArray(parsed) ? parsed.filter((x) => typeof x === "string") : [];
+    }
+    catch {
+        return [];
+    }
+}

package/dist/reranker.d.ts

@@ -0,0 +1,34 @@
+import type { PeonConfig } from "./config.js";
+import type { RankedMemoryRecord } from "./retrieval.js";
+/**
+ * Stage two of two-stage retrieval. The lexical+semantic ranker (RRF) is a high-RECALL
+ * first pass: cheap, deterministic, surfaces everything plausibly relevant. This reranker
+ * is the high-PRECISION second pass: a small, fast LLM (flash-lite) reads the actual query
+ * and the candidate snippets and reorders the top-K by true relevance — catching meaning
+ * that token overlap and cosine miss (negation, intent, the right sense of an ambiguous term).
+ *
+ * It is strictly optional and degrades gracefully: with no API key, AI disabled, an empty
+ * query, too few candidates, or any LLM/parse failure, it returns the input order unchanged.
+ * Only the top-K head is reranked; the tail is left in its original order and appended, so a
+ * truncated or partial model response can never drop or duplicate a candidate.
+ */
+export type FetchLike = (url: string, init: RequestInit) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+}>;
+export interface RerankOptions {
+    config: PeonConfig;
+    /** How many of the top candidates to rerank. Default 20. The rest keep their order. */
+    topK?: number;
+    /** Override the rerank model. Defaults to the (cheap) processing model. */
+    model?: string;
+    /** Injectable fetch — defaults to global fetch. Lets tests run without a network. */
+    fetchImpl?: FetchLike;
+    /** Per-snippet character cap fed to the model (keeps the prompt — and cost — small). Default 240. */
+    snippetChars?: number;
+}
+export declare function rerankRecords(query: string | undefined, records: RankedMemoryRecord[], options: RerankOptions): Promise<RankedMemoryRecord[]>;
+/** Extract the leading JSON array of positive integers from a model response, tolerant of stray prose/fences. */
+export declare function parseOrder(content: string, max: number): number[];

package/dist/reranker.js

@@ -0,0 +1,89 @@
+const DEFAULT_TOP_K = 20;
+const DEFAULT_SNIPPET_CHARS = 240;
+export async function rerankRecords(query, records, options) {
+    const { config } = options;
+    const q = (query ?? "").trim();
+    // Cheap exits — never pay an LLM call when it cannot help.
+    if (!q || records.length < 2)
+        return records;
+    if (config.aiMode === "off" || !config.openRouterApiKey)
+        return records;
+    const topK = Math.max(2, Math.trunc(options.topK ?? DEFAULT_TOP_K));
+    const snippetChars = Math.max(40, Math.trunc(options.snippetChars ?? DEFAULT_SNIPPET_CHARS));
+    const head = records.slice(0, topK);
+    const tail = records.slice(topK);
+    const doFetch = options.fetchImpl ?? globalThis.fetch;
+    if (!doFetch)
+        return records;
+    const numbered = head
+        .map((item, i) => `${i + 1}. [${item.record.type}] ${truncate(item.record.content, snippetChars)}`)
+        .join("\n");
+    const system = "You are a precision reranker for a memory system. Given a user query and a numbered list " +
+        "of candidate memory snippets, decide which snippets best help answer the query. " +
+        "Return ONLY a JSON array of the candidate numbers, ordered from most to least relevant. " +
+        "Include every number exactly once. No prose, no code fences.";
+    const user = `Query: ${q}\n\nCandidates:\n${numbered}\n\nJSON array of numbers (most relevant first):`;
+    try {
+        const response = await doFetch("https://openrouter.ai/api/v1/chat/completions", {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${config.openRouterApiKey}`,
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify({
+                model: options.model ?? config.processingModel,
+                messages: [
+                    { role: "system", content: system },
+                    { role: "user", content: user }
+                ],
+                temperature: 0
+            })
+        });
+        if (!response.ok)
+            return records;
+        const json = (await response.json());
+        const content = json.choices?.[0]?.message?.content ?? "";
+        const order = parseOrder(content, head.length);
+        if (order.length === 0)
+            return records;
+        // Apply the model's order to the head, then append any head items it omitted (in their
+        // original order), then the untouched tail. Guarantees a permutation of the input.
+        const seen = new Set();
+        const reorderedHead = [];
+        for (const n of order) {
+            const idx = n - 1;
+            if (idx >= 0 && idx < head.length && !seen.has(idx)) {
+                seen.add(idx);
+                reorderedHead.push(head[idx]);
+            }
+        }
+        for (let i = 0; i < head.length; i++)
+            if (!seen.has(i))
+                reorderedHead.push(head[i]);
+        return [...reorderedHead, ...tail];
+    }
+    catch {
+        return records; // any failure → first-pass order, never worse than before
+    }
+}
+/** Extract the leading JSON array of positive integers from a model response, tolerant of stray prose/fences. */
+export function parseOrder(content, max) {
+    const match = content.match(/\[[\s\S]*?\]/);
+    if (!match)
+        return [];
+    try {
+        const parsed = JSON.parse(match[0]);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed
+            .map((n) => (typeof n === "number" ? Math.trunc(n) : Number.parseInt(String(n), 10)))
+            .filter((n) => Number.isInteger(n) && n >= 1 && n <= max);
+    }
+    catch {
+        return [];
+    }
+}
+function truncate(text, max) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
+}

package/dist/retrieval.d.ts

@@ -0,0 +1,106 @@
+import { type EmbeddingVector } from "./embeddings.js";
+import type { MemoryRecord, MemoryType } from "./types.js";
+export type RetrievalReasonKind = "query_term" | "entity" | "file" | "type" | "quality" | "recency" | "status" | "semantic";
+export interface RetrievalReason {
+    kind: RetrievalReasonKind;
+    label: string;
+    score: number;
+}
+export interface RankedMemoryRecord {
+    record: MemoryRecord;
+    score: number;
+    reasons: RetrievalReason[];
+    explanation: string;
+}
+export interface SemanticRetrievalInput {
+    /** Embedding of the query string. */
+    queryVector: EmbeddingVector;
+    /** Record id → its stored embedding vector. */
+    vectorById: Map<string, EmbeddingVector>;
+    /** How strongly cosine similarity counts toward the final score. Default 6. */
+    weight?: number;
+    /** Cosine similarities below this contribute nothing (filters noise). Default 0.15. */
+    minSimilarity?: number;
+}
+export interface RetrievalOptions {
+    now?: Date | string | number;
+    limit?: number;
+    typeWeights?: Partial<Record<MemoryType, number>>;
+    /** When provided (and a query is given), blends semantic similarity into ranking. */
+    semantic?: SemanticRetrievalInput;
+    /** Per-record entity-graph activation (id → score). Fused as a signal AND admits an
+     *  associatively-activated belief through the relevance gate, so a strong association can
+     *  enter the top-K instead of being appended after the direct hits. See computeGraphActivation. */
+    graphActivation?: Map<string, number>;
+}
+export interface ContextSelectionOptions {
+    maxChars: number;
+    recordFormatter?: (item: RankedMemoryRecord) => string;
+}
+export interface ContextSelection {
+    records: RankedMemoryRecord[];
+    omitted: RankedMemoryRecord[];
+    totalChars: number;
+    maxChars: number;
+}
+/**
+ * Hybrid retrieval by Reciprocal Rank Fusion. Each signal (lexical, semantic,
+ * quality, recency, reinforcement strength) ranks the relevance-gated candidates
+ * independently; we fuse by Σ 1/(k+rank). RRF is weight-free — it removes the
+ * fragile hand-tuned score constants by comparing RANKS, which are commensurable
+ * across signals where raw scores are not. Pinned beliefs are boosted; archived/
+ * superseded are excluded by default (they are the long-term tier, not working memory).
+ */
+export declare function rankMemoryRecords(records: MemoryRecord[], query: string | undefined, options?: RetrievalOptions): RankedMemoryRecord[];
+export declare function selectMemoryRecordsForContext(rankedRecords: RankedMemoryRecord[], options: ContextSelectionOptions): ContextSelection;
+/** Default trade-off: 0.7 weight on relevance, 0.3 on novelty. Tuned for coverage without losing the top hit. */
+export declare const DEFAULT_MMR_LAMBDA = 0.7;
+/**
+ * Re-order ranked records by Maximal Marginal Relevance so the injected block has
+ * COVERAGE instead of five paraphrases of the same belief. Each pick maximizes
+ *   λ·relevance − (1−λ)·maxSimilarity(candidate, alreadyPicked)
+ * Relevance is the record's existing fused score (max-normalized to [0,1] within the
+ * set); similarity is lexical Jaccard over content+entity tokens — cheap, deterministic,
+ * and embedding-free so it works in pure local-first mode. The single most relevant
+ * record is always selected first, so the top hit is never displaced by diversification.
+ */
+export declare function diversifyByMMR(records: RankedMemoryRecord[], lambda?: number): RankedMemoryRecord[];
+export interface GraphExpandOptions {
+    /** How many of the top ranked records seed the activation. Default 8. */
+    seedDepth?: number;
+    /** Max neighbours to pull in. Default 6. */
+    maxNeighbors?: number;
+    /** Global decay on the 1-hop spread (keeps neighbours supplementary). Default 0.5. */
+    damping?: number;
+    /** Weight for code-namespace entities vs domain (file/symbol co-occurrence is weaker signal). Default 0.4. */
+    codeWeight?: number;
+    /** Skip entities mentioned by more than this many beliefs — super-hub hairball guard. Default 40. */
+    hubDegreeCap?: number;
+}
+/**
+ * Entity-graph spreading activation (the associative-recall layer). Lexical/semantic ranking
+ * finds beliefs that match the QUERY; this finds beliefs in the ANSWER's neighbourhood by
+ * spreading activation from the top hits through shared entities, with three brain-like rules
+ * the old flat 1-hop expander lacked:
+ *   - DISTANCE DECAY — a global damping (λ) keeps neighbours below direct matches.
+ *   - MULTI-SOURCE SUMMATION — a belief lit through several shared entities (or several seeds)
+ *     accumulates activation, so it outranks one lit through a single weak link.
+ *   - HUB DAMPING — rare entities transmit more activation (1/log₂(2+degree)); super-hubs
+ *     (e.g. a file mentioned by 80 beliefs) are skipped so the graph isn't a hairball.
+ * Domain entities (people/papers/concepts) spread more than code entities. Pure + deterministic.
+ * Neighbours come back with small scores in their own band and are meant to be appended AFTER
+ * the direct results, never displacing them.
+ */
+/**
+ * Raw spreading activation: id → accumulated activation for beliefs in the seeds' entity
+ * neighbourhood (excluding the seeds themselves). The associative substrate, shared by the
+ * fused-ranking path (passed as RetrievalOptions.graphActivation) and the legacy append path
+ * (expandByEntityGraph). Excludes seed ids so direct hits aren't double-counted.
+ */
+export declare function computeGraphActivation(seeds: RankedMemoryRecord[], pool: MemoryRecord[], options?: GraphExpandOptions): Map<string, number>;
+/**
+ * Entity-graph spreading activation, formatted as standalone neighbour records (legacy append
+ * path + the unit tests). The fused-ranking path uses computeGraphActivation directly via
+ * rankMemoryRecords' graphActivation option, which lets associations compete inside the top-K.
+ */
+export declare function expandByEntityGraph(seeds: RankedMemoryRecord[], pool: MemoryRecord[], options?: GraphExpandOptions): RankedMemoryRecord[];