@atomicmemory/core 1.0.0

package/dist/services/relevance-policy.js

@@ -0,0 +1,109 @@
+/**
+ * Score semantics and relevance threshold policy for retrieval packaging.
+ */
+import { classifyQueryDetailed, resolveRecallBypass } from './retrieval-policy.js';
+const INTEGRATION_SOURCE_PREFIXES = ['integration-', 'integration_', 'integration:', 'integration/'];
+const KNOWN_INTEGRATION_SOURCE_SITES = new Set([
+    'integration',
+    'gmail',
+    'gmail.com',
+    'google-drive',
+    'google_drive',
+    'drive.google.com',
+    'docs.google.com',
+    'mail.google.com',
+    'x.com',
+    'twitter',
+    'twitter.com',
+]);
+export function resolveRelevanceGate(query, requestedThreshold, runtimeConfig, context = {}) {
+    const queryLabel = classifyQueryDetailed(query).label;
+    // Explicit caller policy is authoritative; recall-preserving bypasses below
+    // only relax the config default when the request has not supplied a floor.
+    if (requestedThreshold !== undefined) {
+        return buildGate(requestedThreshold, 'request', 'caller-threshold', queryLabel);
+    }
+    const bypassReason = resolveRecallBypass(query, queryLabel, context);
+    if (bypassReason)
+        return { threshold: null, source: 'disabled', reason: bypassReason, queryLabel };
+    return buildGate(runtimeConfig.similarityThreshold, 'config', 'direct-query-default', queryLabel);
+}
+export function applyRelevanceFilter(memories, gate) {
+    const scored = memories.map(withScoreSemantics);
+    const decisions = scored.map((memory) => buildDecision(memory, gate));
+    if (gate.threshold === null)
+        return { memories: scored, decisions, removedIds: [] };
+    const keptIds = new Set(decisions.filter((decision) => decision.decision === 'kept').map((decision) => decision.id));
+    return {
+        memories: scored.filter((memory) => keptIds.has(memory.id)),
+        decisions,
+        removedIds: decisions.filter((decision) => decision.decision === 'filtered').map((decision) => decision.id),
+    };
+}
+function withScoreSemantics(memory) {
+    const semanticSimilarity = finiteOrZero(memory.semantic_similarity ?? memory.similarity);
+    const rankingScore = finiteOrZero(memory.ranking_score ?? memory.score);
+    const relevance = clampUnit(memory.relevance ?? semanticSimilarity);
+    return {
+        ...memory,
+        semantic_similarity: semanticSimilarity,
+        ranking_score: rankingScore,
+        relevance,
+    };
+}
+function buildGate(rawThreshold, source, reason, queryLabel) {
+    const threshold = clampUnit(rawThreshold);
+    return { threshold, source, reason, queryLabel };
+}
+function buildDecision(memory, gate) {
+    const sourceKind = classifySourceKind(memory.source_site);
+    const threshold = gate.threshold;
+    const kept = threshold === null || memory.relevance >= threshold;
+    return {
+        id: memory.id,
+        sourceSite: memory.source_site,
+        sourceKind,
+        namespace: memory.namespace ?? null,
+        semanticSimilarity: memory.semantic_similarity,
+        rankingScore: memory.ranking_score,
+        relevance: memory.relevance,
+        threshold,
+        decision: kept ? 'kept' : 'filtered',
+        reason: buildReason(kept, gate, sourceKind),
+    };
+}
+function buildReason(kept, gate, sourceKind) {
+    if (gate.threshold === null)
+        return gate.reason;
+    if (sourceKind === 'integration') {
+        return kept ? 'integration-meets-threshold' : 'integration-below-threshold';
+    }
+    return kept ? 'meets-threshold' : 'below-threshold';
+}
+function classifySourceKind(sourceSite) {
+    const normalized = normalizeSourceSite(sourceSite);
+    if (INTEGRATION_SOURCE_PREFIXES.some((prefix) => normalized.startsWith(prefix))) {
+        return 'integration';
+    }
+    return KNOWN_INTEGRATION_SOURCE_SITES.has(normalized) ? 'integration' : 'local';
+}
+function normalizeSourceSite(sourceSite) {
+    const trimmed = sourceSite.trim().toLowerCase();
+    if (!trimmed)
+        return trimmed;
+    try {
+        const parsed = new URL(trimmed.includes('://') ? trimmed : `https://${trimmed}`);
+        return parsed.hostname.replace(/^www\./, '');
+    }
+    catch {
+        return trimmed;
+    }
+}
+function finiteOrZero(value) {
+    return Number.isFinite(value) ? value : 0;
+}
+function clampUnit(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.max(0, Math.min(1, value));
+}

package/dist/services/rerank.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Cross-encoder reranker for search-pipeline RRF results.
+ *
+ * Re-scores the top-N candidates from the fused RRF output by asking an LLM
+ * to rate (query, candidate) relevance, then promotes the top-K. Mirrors the
+ * primitive Hindsight uses but at AM's latency tier (~50-150 ms added p95).
+ *
+ * Principled, no-regex: an LLM-learned scoring function. No query-text pattern
+ * matching. The reranker activates uniformly for all queries when the config
+ * flag is on.
+ *
+ * Feature flag: rerankerEnabled (default OFF).
+ *
+ * See benchmarks-sprint3/2026-05-10-am-baseline-and-rerank-design.md.
+ */
+import type { LLMProvider } from './llm.js';
+import type { SearchResult } from '../db/repository-types.js';
+export declare class RerankerError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * Rerank a list of search results by LLM-judged relevance to the query.
+ *
+ * Returns a new array sorted by reranker score (descending). Original
+ * SearchResult fields are preserved; the returned array preserves length
+ * (no candidates dropped).
+ *
+ * Fail-closed: throws RerankerError on LLM failure or invalid output.
+ * Caller is expected to catch and fall back to the un-reranked list.
+ */
+export declare function llmRerank(query: string, candidates: SearchResult[], llmClient?: LLMProvider): Promise<SearchResult[]>;

package/dist/services/rerank.js

@@ -0,0 +1,118 @@
+/**
+ * Cross-encoder reranker for search-pipeline RRF results.
+ *
+ * Re-scores the top-N candidates from the fused RRF output by asking an LLM
+ * to rate (query, candidate) relevance, then promotes the top-K. Mirrors the
+ * primitive Hindsight uses but at AM's latency tier (~50-150 ms added p95).
+ *
+ * Principled, no-regex: an LLM-learned scoring function. No query-text pattern
+ * matching. The reranker activates uniformly for all queries when the config
+ * flag is on.
+ *
+ * Feature flag: rerankerEnabled (default OFF).
+ *
+ * See benchmarks-sprint3/2026-05-10-am-baseline-and-rerank-design.md.
+ */
+import { llm as defaultLlm } from './llm.js';
+import { extractFirstJsonObject } from './extraction.js';
+const RERANK_MAX_TOKENS = 512;
+const RERANK_DEFAULT_TOP_N = 20;
+const RERANK_CANDIDATE_CONTENT_CHARS = 600;
+const RERANK_SYSTEM_PROMPT = [
+    'You score memory snippets by how well each one helps answer the user query.',
+    '',
+    'Rules:',
+    '- Read the query and each candidate carefully.',
+    '- For each candidate, return a relevance score in [0, 1] where:',
+    '    1.0 = directly answers the query',
+    '    0.5 = related but does not answer directly',
+    '    0.0 = unrelated',
+    '- Output a JSON object: {"scores": [s0, s1, s2, ...]} in candidate order.',
+    '- Do NOT include text outside the JSON. No markdown fences.',
+].join('\n');
+export class RerankerError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'RerankerError';
+    }
+}
+/**
+ * Rerank a list of search results by LLM-judged relevance to the query.
+ *
+ * Returns a new array sorted by reranker score (descending). Original
+ * SearchResult fields are preserved; the returned array preserves length
+ * (no candidates dropped).
+ *
+ * Fail-closed: throws RerankerError on LLM failure or invalid output.
+ * Caller is expected to catch and fall back to the un-reranked list.
+ */
+export async function llmRerank(query, candidates, llmClient = defaultLlm) {
+    if (candidates.length === 0)
+        return candidates;
+    const limit = Math.min(candidates.length, RERANK_DEFAULT_TOP_N);
+    const slice = candidates.slice(0, limit);
+    const messages = [
+        { role: 'system', content: RERANK_SYSTEM_PROMPT },
+        { role: 'user', content: buildRerankUserMessage(query, slice) },
+    ];
+    let raw;
+    try {
+        raw = await llmClient.chat(messages, {
+            temperature: 0,
+            jsonMode: true,
+            maxTokens: RERANK_MAX_TOKENS,
+        });
+    }
+    catch (err) {
+        throw new RerankerError(`reranker LLM call failed: ${err.message}`, err);
+    }
+    if (!raw)
+        throw new RerankerError('reranker returned empty content');
+    const cleaned = extractFirstJsonObject(raw);
+    let parsed;
+    try {
+        parsed = JSON.parse(cleaned);
+    }
+    catch (err) {
+        throw new RerankerError(`reranker returned non-JSON: ${cleaned.slice(0, 200)}`, err);
+    }
+    const scores = validateScores(parsed.scores, slice.length);
+    return applyScores(slice, scores, candidates.slice(limit));
+}
+function buildRerankUserMessage(query, candidates) {
+    const blocks = candidates.map((c, i) => {
+        const content = (c.content ?? '').trim().slice(0, RERANK_CANDIDATE_CONTENT_CHARS);
+        return `[${i}] ${content}`;
+    });
+    return [
+        'QUERY:',
+        query.trim().slice(0, 2000),
+        '',
+        `CANDIDATES (${candidates.length}):`,
+        blocks.join('\n'),
+        '',
+        `Return JSON: {"scores": [${candidates.map(() => 's').join(', ')}]} where each s is in [0, 1].`,
+    ].join('\n');
+}
+function validateScores(raw, expectedLength) {
+    if (!Array.isArray(raw)) {
+        throw new RerankerError(`scores must be an array, got ${typeof raw}`);
+    }
+    if (raw.length !== expectedLength) {
+        throw new RerankerError(`scores length ${raw.length} != expected ${expectedLength}`);
+    }
+    return raw.map((s, i) => {
+        const n = typeof s === 'number' ? s : Number(s);
+        if (!Number.isFinite(n)) {
+            throw new RerankerError(`score[${i}] is not a finite number: ${String(s)}`);
+        }
+        return Math.max(0, Math.min(1, n));
+    });
+}
+function applyScores(scored, scores, unscored) {
+    const indexed = scored.map((c, i) => ({ result: c, score: scores[i] }));
+    indexed.sort((a, b) => b.score - a.score);
+    return [...indexed.map((x) => x.result), ...unscored];
+}

package/dist/services/reranker.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Cross-encoder reranker using a configurable Transformers.js sequence classifier.
+ *
+ * Scores (query, document) pairs jointly for more accurate relevance ranking
+ * than bi-encoder cosine similarity alone. Runs on CPU via ONNX Runtime.
+ *
+ * Enable via CROSS_ENCODER_ENABLED=true and choose the model with
+ * CROSS_ENCODER_MODEL.
+ */
+import type { SearchResult } from '../db/memory-repository.js';
+import { type CrossEncoderDtype } from '../config.js';
+export interface RerankerRuntimeConfig {
+    crossEncoderModel: string;
+    crossEncoderDtype: CrossEncoderDtype;
+}
+/**
+ * Rerank candidates using cross-encoder scoring.
+ * Replaces .score on each SearchResult; preserves .similarity for MMR.
+ */
+export declare function rerankCandidates(query: string, candidates: SearchResult[], runtimeConfig?: RerankerRuntimeConfig): Promise<SearchResult[]>;

package/dist/services/reranker.js

@@ -0,0 +1,99 @@
+/**
+ * Cross-encoder reranker using a configurable Transformers.js sequence classifier.
+ *
+ * Scores (query, document) pairs jointly for more accurate relevance ranking
+ * than bi-encoder cosine similarity alone. Runs on CPU via ONNX Runtime.
+ *
+ * Enable via CROSS_ENCODER_ENABLED=true and choose the model with
+ * CROSS_ENCODER_MODEL.
+ */
+import { config } from '../config.js';
+let tokenizer = null;
+let model = null;
+let loadedModelKey = null;
+let loadPromise = null;
+/** Serialize ONNX inference to prevent mutex corruption (see onnx-stability-issue.md). */
+let inferenceQueue = Promise.resolve();
+async function loadTokenizer(modelId) {
+    const { AutoTokenizer } = await import('@huggingface/transformers');
+    return AutoTokenizer.from_pretrained(modelId);
+}
+async function loadModel(modelId, runtimeConfig) {
+    const { AutoModelForSequenceClassification } = await import('@huggingface/transformers');
+    return AutoModelForSequenceClassification.from_pretrained(modelId, {
+        dtype: runtimeConfig.crossEncoderDtype,
+    });
+}
+function buildRerankerConfigKey(runtimeConfig) {
+    return `${runtimeConfig.crossEncoderModel}:${runtimeConfig.crossEncoderDtype}`;
+}
+async function ensureLoaded(runtimeConfig = config) {
+    const modelId = runtimeConfig.crossEncoderModel;
+    const modelKey = buildRerankerConfigKey(runtimeConfig);
+    if (tokenizer && model && loadedModelKey === modelKey)
+        return;
+    if (loadPromise) {
+        await loadPromise;
+        return;
+    }
+    loadPromise = (async () => {
+        console.log(`[reranker] Loading ${modelId} (${runtimeConfig.crossEncoderDtype})...`);
+        const start = Date.now();
+        [tokenizer, model] = await Promise.all([loadTokenizer(modelId), loadModel(modelId, runtimeConfig)]);
+        loadedModelKey = modelKey;
+        console.log(`[reranker] Loaded ${modelId} (${runtimeConfig.crossEncoderDtype}) in ${Date.now() - start}ms`);
+    })();
+    try {
+        await loadPromise;
+    }
+    finally {
+        loadPromise = null;
+    }
+}
+function sigmoid(x) {
+    return 1 / (1 + Math.exp(-x));
+}
+/**
+ * Rerank candidates using cross-encoder scoring.
+ * Replaces .score on each SearchResult; preserves .similarity for MMR.
+ */
+export async function rerankCandidates(query, candidates, runtimeConfig = config) {
+    if (candidates.length === 0)
+        return candidates;
+    await ensureLoaded(runtimeConfig);
+    const start = Date.now();
+    const queries = candidates.map(() => query);
+    const documents = candidates.map((c) => c.content);
+    const inputs = tokenizer(queries, {
+        text_pair: documents,
+        padding: true,
+        truncation: true,
+    });
+    const scores = await new Promise((resolve, reject) => {
+        inferenceQueue = inferenceQueue.then(async () => {
+            try {
+                const output = await model(inputs);
+                const logits = Array.from(output.logits.data);
+                resolve(logits.map(sigmoid));
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+    });
+    // Blend cross-encoder relevance with original temporal-aware score.
+    // The cross-encoder scores pure textual relevance (0-1) but has no temporal
+    // signal. Without blending, a semantically-closer old fact will always outrank
+    // a newer superseding fact. We normalize both signals to [0,1] and combine:
+    //   blended = crossEncoderWeight * ceScore + (1 - crossEncoderWeight) * normalizedOriginal
+    const crossEncoderWeight = 0.7;
+    const maxOriginal = Math.max(...candidates.map((c) => c.score), 1e-9);
+    const reranked = candidates.map((candidate, i) => ({
+        ...candidate,
+        score: crossEncoderWeight * scores[i] + (1 - crossEncoderWeight) * (candidate.score / maxOriginal),
+    }));
+    reranked.sort((a, b) => b.score - a.score);
+    const ms = Date.now() - start;
+    console.log(`[reranker] Scored ${candidates.length} candidates with ${runtimeConfig.crossEncoderModel} (${runtimeConfig.crossEncoderDtype}) in ${ms}ms (top: ${reranked[0]?.score.toFixed(3)})`);
+    return reranked;
+}

package/dist/services/retrieval-channel-rules.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Channel emission rules for retrieval-format injection.
+ *
+ * Each helper encodes which prompt channels are appropriate for a given
+ * question type. The principle: emit only the channels that aid that
+ * specific question type; suppress everything else so the answer LLM
+ * isn't distracted by paraphrased content competing with raw facts.
+ *
+ * Smoke v1/v2 evidence: emitting all channels for every query (the "OTHER
+ * keeps everything" rule) regressed IF/KU/IE by 0.25–0.75 because Haiku
+ * fixated on paraphrased TIMELINE/EVENT_CHAIN content above the raw fact
+ * block and produced "context does not contain information" even when
+ * the literal fact was present. Conservative default: OTHER gets NO
+ * auxiliary channels — let the LLM work with raw retrieved facts unless
+ * the question type explicitly benefits from a channel.
+ */
+import { QuestionType } from './answer-format.js';
+/**
+ * Whether to emit the ## EVENT_CHAIN channel.
+ * Only ORDERED_LIST queries need chronological per-entity event chains.
+ * OTHER suppresses it — chains paraphrase content and compete with raw facts.
+ */
+export declare function shouldEmitEventChain(qt: QuestionType): boolean;
+/**
+ * Whether to emit the ## OBSERVATIONS channel (Reflect-synthesized).
+ * Only CONTRADICTION and SUMMARY queries benefit; other types use raw facts.
+ */
+export declare function shouldEmitObservations(qt: QuestionType): boolean;
+/**
+ * Whether to apply the Layer 1 per-type format hint.
+ * Skipped for PREFERENCE (no hint exists) and OTHER (no classification
+ * matched, no rationale to constrain the answer format).
+ */
+export declare function shouldApplyFormatHint(qt: QuestionType): boolean;

package/dist/services/retrieval-channel-rules.js

@@ -0,0 +1,41 @@
+/**
+ * Channel emission rules for retrieval-format injection.
+ *
+ * Each helper encodes which prompt channels are appropriate for a given
+ * question type. The principle: emit only the channels that aid that
+ * specific question type; suppress everything else so the answer LLM
+ * isn't distracted by paraphrased content competing with raw facts.
+ *
+ * Smoke v1/v2 evidence: emitting all channels for every query (the "OTHER
+ * keeps everything" rule) regressed IF/KU/IE by 0.25–0.75 because Haiku
+ * fixated on paraphrased TIMELINE/EVENT_CHAIN content above the raw fact
+ * block and produced "context does not contain information" even when
+ * the literal fact was present. Conservative default: OTHER gets NO
+ * auxiliary channels — let the LLM work with raw retrieved facts unless
+ * the question type explicitly benefits from a channel.
+ */
+import { QuestionType } from './answer-format.js';
+/**
+ * Whether to emit the ## EVENT_CHAIN channel.
+ * Only ORDERED_LIST queries need chronological per-entity event chains.
+ * OTHER suppresses it — chains paraphrase content and compete with raw facts.
+ */
+export function shouldEmitEventChain(qt) {
+    return qt === QuestionType.ORDERED_LIST;
+}
+/**
+ * Whether to emit the ## OBSERVATIONS channel (Reflect-synthesized).
+ * Only CONTRADICTION and SUMMARY queries benefit; other types use raw facts.
+ */
+export function shouldEmitObservations(qt) {
+    return qt === QuestionType.CONTRADICTION
+        || qt === QuestionType.SUMMARY;
+}
+/**
+ * Whether to apply the Layer 1 per-type format hint.
+ * Skipped for PREFERENCE (no hint exists) and OTHER (no classification
+ * matched, no rationale to constrain the answer format).
+ */
+export function shouldApplyFormatHint(qt) {
+    return qt !== QuestionType.PREFERENCE && qt !== QuestionType.OTHER;
+}

package/dist/services/retrieval-config-overlay.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @file Per-request config overlay primitives.
+ *
+ * Supports the `config_override` request-body field on memory ingest
+ * and search routes. Three responsibilities:
+ *
+ *   1. `applyConfigOverride` — shallow-merge a validated flat override
+ *      onto the startup `RuntimeConfig`. Because the override shape
+ *      matches the flat `RuntimeConfig` field names one-for-one, this
+ *      is a genuine single-line `{ ...base, ...override }` — no
+ *      mapping layer, no nested traversal.
+ *
+ *   2. `hashEffectiveConfig` — stable SHA-256 over the effective config,
+ *      serialized with deterministically-sorted keys, returned as
+ *      `sha256:<hex>`. Emitted via the `X-Atomicmem-Effective-Config-Hash`
+ *      response header so callers can link traces to a canonical config
+ *      fingerprint.
+ *
+ *   3. `summarizeOverrideKeys` — comma-separated list of top-level keys
+ *      present in the override object, for the
+ *      `X-Atomicmem-Config-Override-Keys` header.
+ *
+ * Design reference: atomicmemory-research/docs/core-repo/design/
+ * per-request-config-override.md §2.3, §2.5.
+ */
+import type { RuntimeConfig } from '../config.js';
+/** Merge a validated override on top of the startup runtime config. */
+export declare function applyConfigOverride(base: RuntimeConfig, override: Partial<RuntimeConfig>): RuntimeConfig;
+/**
+ * SHA-256 fingerprint of the effective config. Keys are sorted before
+ * serialization so the hash is stable regardless of construction order.
+ * Returned in the `sha256:<hex>` form emitted on the response header.
+ */
+export declare function hashEffectiveConfig(cfg: RuntimeConfig): string;
+/** Comma-separated list of keys present in the override object. */
+export declare function summarizeOverrideKeys(override: Partial<RuntimeConfig>): string;

package/dist/services/retrieval-config-overlay.js

@@ -0,0 +1,44 @@
+/**
+ * @file Per-request config overlay primitives.
+ *
+ * Supports the `config_override` request-body field on memory ingest
+ * and search routes. Three responsibilities:
+ *
+ *   1. `applyConfigOverride` — shallow-merge a validated flat override
+ *      onto the startup `RuntimeConfig`. Because the override shape
+ *      matches the flat `RuntimeConfig` field names one-for-one, this
+ *      is a genuine single-line `{ ...base, ...override }` — no
+ *      mapping layer, no nested traversal.
+ *
+ *   2. `hashEffectiveConfig` — stable SHA-256 over the effective config,
+ *      serialized with deterministically-sorted keys, returned as
+ *      `sha256:<hex>`. Emitted via the `X-Atomicmem-Effective-Config-Hash`
+ *      response header so callers can link traces to a canonical config
+ *      fingerprint.
+ *
+ *   3. `summarizeOverrideKeys` — comma-separated list of top-level keys
+ *      present in the override object, for the
+ *      `X-Atomicmem-Config-Override-Keys` header.
+ *
+ * Design reference: atomicmemory-research/docs/core-repo/design/
+ * per-request-config-override.md §2.3, §2.5.
+ */
+import { createHash } from 'node:crypto';
+/** Merge a validated override on top of the startup runtime config. */
+export function applyConfigOverride(base, override) {
+    return { ...base, ...override };
+}
+/**
+ * SHA-256 fingerprint of the effective config. Keys are sorted before
+ * serialization so the hash is stable regardless of construction order.
+ * Returned in the `sha256:<hex>` form emitted on the response header.
+ */
+export function hashEffectiveConfig(cfg) {
+    const canonical = JSON.stringify(cfg, Object.keys(cfg).sort());
+    const hex = createHash('sha256').update(canonical).digest('hex');
+    return `sha256:${hex}`;
+}
+/** Comma-separated list of keys present in the override object. */
+export function summarizeOverrideKeys(override) {
+    return Object.keys(override).sort().join(',');
+}

package/dist/services/retrieval-format.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Provenance-first retrieval formatting helpers.
+ *
+ * Supports two modes:
+ *   - Full: each memory's complete content is included (default)
+ *   - Staged (L0): only summaries are included, with memory IDs for
+ *     on-demand expansion via POST /v1/memories/expand. Reduces injection
+ *     tokens by ~80% for typical workloads.
+ */
+import type { Reflection } from '../db/reflections-repository.js';
+import type { EventChain } from './event-chain-detector.js';
+import { QuestionType } from './answer-format.js';
+import type { SearchResult } from '../db/memory-repository.js';
+import type { TierAssignment } from './tiered-loading.js';
+import type { RetrievalMode } from './memory-service-types.js';
+/**
+ * Packaging observability signal — records whether and how packaging
+ * reordered memories vs. raw retrieval score order. Enables A/B evals
+ * to distinguish packaging-caused flips from retrieval noise.
+ */
+export interface PackagingSignal {
+    /** True if packaging changed the memory order from score-descending. */
+    reordered: boolean;
+    /** Number of distinct episodes (sessions) in the result set. */
+    episodeCount: number;
+    /** Number of memories classified as answer-bearing by session-packaging heuristics. */
+    answerBearingCount: number;
+    /** Number of memories classified as context (non-answer-bearing). */
+    contextCount: number;
+    /** Kendall tau distance: number of pairwise swaps between score order and packaged order (0 = identical). */
+    reorderDistance: number;
+}
+/**
+ * Compare score-descending order to the order produced by packaging
+ * (session-priority sort, answer-bearing promotion, chronological).
+ */
+export declare function computePackagingSignal(memories: SearchResult[]): PackagingSignal;
+export interface RetrievalCitation {
+    memory_id: string;
+    source_site: string;
+    created_at: string;
+    importance: number;
+}
+/**
+ * Recap row promoted into the injection's `## EPISODES` channel.
+ * One element per recap; `topic` becomes the section header and
+ * `narrative` is the synthesized recap text.
+ */
+export interface EpisodeForInjection {
+    topic: string;
+    narrative: string;
+}
+export interface RetrievalFormatOptions {
+    stagedLoadingEnabled?: boolean;
+    userProfileText?: string;
+    episodes?: EpisodeForInjection[];
+    entityFacts?: import('./episode-fetcher.js').EntityFactForInjection[];
+}
+export declare function buildCitations(memories: SearchResult[]): RetrievalCitation[];
+/** Simple dash-delimited injection format (no XML). */
+export declare function formatSimpleInjection(memories: SearchResult[]): string;
+export declare function formatInjection(memories: SearchResult[], options?: RetrievalFormatOptions): string;
+export interface FormatTieredOptions {
+    /**
+     * When `false`, the renderer omits the trailing temporal evidence
+     * block / timeline summary entirely. The caller is responsible for
+     * setting this when the budget can't fit the extra-block tokens
+     * after the included memories are accounted for — without this
+     * escape hatch, the rendered injection would silently exceed the
+     * caller's `tokenBudget`. Default `true` preserves prior behavior.
+     */
+    includeExtraBlock?: boolean;
+}
+/**
+ * Format injection using tier assignments from the budget allocator.
+ * Uses a compact line-oriented format so tier metadata does not erase
+ * the token savings from L0/L1 compression.
+ *
+ * Iteration is driven off `assignments`: the rendered output contains
+ * exactly the memories named by the assignment list, in chronological
+ * order. Memories present in the input but missing from `assignments`
+ * are not rendered — that's how excluded-by-budget memories stay
+ * absent from the package. Throws when an assignment references a
+ * memory id that isn't in the input list (caller bug).
+ */
+export declare function formatTieredInjection(memories: SearchResult[], assignments: TierAssignment[], query?: string, options?: FormatTieredOptions): string;
+export interface InjectionBuildResult {
+    injectionText: string;
+    tierAssignments?: TierAssignment[];
+    expandIds?: string[];
+    estimatedContextTokens?: number;
+    /**
+     * True when the requested token budget changed the package content
+     * relative to the unconstrained tiered package — either eligible
+     * memories were omitted because their L0 representation did not fit,
+     * or eligible memories were kept at a reduced tier solely because
+     * the budget prevented richer eligible content (including
+     * query-term-revealing upgrades). Quota-driven demotion (e.g.
+     * MAX_L2_MEMORIES) is packaging policy and is NOT flagged.
+     */
+    budgetConstrained: boolean;
+    /**
+     * Memories that actually contributed to the rendered package.
+     * In tiered mode this is `deduplicateCompositeMembersHard(memories) - excluded`.
+     * In flat mode this equals the input memories. Downstream consumers
+     * (response.memories, citations, side effects) should use this set
+     * so what they see matches what was injected.
+     */
+    includedMemories: SearchResult[];
+}
+/**
+ * Build injection text from search results, optionally using tiered packaging.
+ * Flat mode returns the existing chronological format.
+ * Tiered mode assigns L0/L1/L2 tiers under the caller's token budget.
+ * When no token budget is provided, tiered packaging is unbounded:
+ * quotas still shape rich-detail tiers, but budget_constrained remains
+ * false because no caller budget was applied.
+ */
+export declare function buildInjection(memories: SearchResult[], query: string, mode: RetrievalMode, tokenBudget?: number, userProfileText?: string, episodes?: EpisodeForInjection[], entityFacts?: import('./episode-fetcher.js').EntityFactForInjection[], chains?: EventChain[], reflections?: readonly Reflection[], questionType?: QuestionType): InjectionBuildResult;