@atomicmemory/core 1.0.0

package/dist/services/reflect-jobs.js

@@ -0,0 +1,36 @@
+export async function processOnePendingJob(deps) {
+    const [job] = await deps.jobs.fetchPending(1);
+    if (!job)
+        return false;
+    await deps.jobs.markInProgress(job.id);
+    try {
+        await deps.runReflect(job.userId, job.conversationId);
+        await deps.jobs.markCompleted(job.id);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        await deps.jobs.markFailed(job.id, msg);
+    }
+    return true;
+}
+export function startReflectWorker(deps, pollMs) {
+    let stopped = false;
+    const tick = async () => {
+        if (stopped)
+            return;
+        try {
+            const didWork = await processOnePendingJob(deps);
+            if (!didWork) {
+                await new Promise(r => setTimeout(r, pollMs));
+            }
+        }
+        catch (e) {
+            console.error('[reflect-worker] unexpected error:', e);
+            await new Promise(r => setTimeout(r, pollMs * 2));
+        }
+        if (!stopped)
+            void tick();
+    };
+    void tick();
+    return { stop: () => { stopped = true; } };
+}

package/dist/services/reflect-prompts.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Prompt assembly + Anthropic tool-use schema for the async Reflect step.
+ *
+ * The Reflect call presents Sonnet with a chronologically-sorted list of the
+ * session's raw memories (each with its memory id and observed_at) and asks
+ * Sonnet to consolidate them into a small set of typed observations. Each
+ * observation MUST cite the memory_ids it draws from, so retrieval can verify
+ * evidence still exists when the observation is later read by the answer LLM.
+ *
+ * Tool-use guarantees structured output — Sonnet returns a JSON payload that
+ * matches REFLECT_TOOL_SCHEMA, eliminating the freeform-prose parsing failures
+ * we saw with the Sprint 3 verifier pass.
+ */
+export interface ReflectMemoryInput {
+    id: string;
+    text: string;
+    observedAt: Date;
+}
+export interface ReflectMessages {
+    system: string;
+    user: string;
+}
+export declare const REFLECT_TOOL_SCHEMA: {
+    readonly name: "record_observations";
+    readonly description: "Persist the consolidated observations for this conversation.";
+    readonly input_schema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly observations: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "object";
+                    readonly required: readonly ["text", "type", "evidence_memory_ids"];
+                    readonly properties: {
+                        readonly text: {
+                            readonly type: "string";
+                        };
+                        readonly type: {
+                            readonly type: "string";
+                            readonly enum: readonly ["entity_state", "event_summary", "preference", "contradiction", "decision", "numeric_value"];
+                        };
+                        readonly evidence_memory_ids: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        readonly required: readonly ["observations"];
+    };
+};
+export declare function buildReflectMessages(memories: readonly ReflectMemoryInput[]): ReflectMessages;
+/**
+ * Input shape for entity-card synthesis. One observation per row, with the
+ * observation_id citation, observation date, and observation text. Used by
+ * the always-on ENTITY_CARD channel synthesizer.
+ */
+export interface EntityCardObservationInput {
+    id: string;
+    text: string;
+    observedAt: Date;
+}
+/**
+ * Assemble the messages for an entity-card synthesis call. The model sees the
+ * prior card (if any) and a list of new observations citing their obs_ids
+ * and dates, and is asked to output ONLY the updated card text.
+ */
+export declare function buildEntityCardMessages(entityName: string, priorCardText: string | null, observations: readonly EntityCardObservationInput[]): ReflectMessages;

package/dist/services/reflect-prompts.js

@@ -0,0 +1,99 @@
+/**
+ * Prompt assembly + Anthropic tool-use schema for the async Reflect step.
+ *
+ * The Reflect call presents Sonnet with a chronologically-sorted list of the
+ * session's raw memories (each with its memory id and observed_at) and asks
+ * Sonnet to consolidate them into a small set of typed observations. Each
+ * observation MUST cite the memory_ids it draws from, so retrieval can verify
+ * evidence still exists when the observation is later read by the answer LLM.
+ *
+ * Tool-use guarantees structured output — Sonnet returns a JSON payload that
+ * matches REFLECT_TOOL_SCHEMA, eliminating the freeform-prose parsing failures
+ * we saw with the Sprint 3 verifier pass.
+ */
+const SYSTEM_PROMPT = [
+    'You are consolidating a single conversation\'s raw memories into a small set of typed observations.',
+    'Each observation must (a) be answerable from the cited evidence_memory_ids alone, (b) prefer concrete factual claims over narrative, (c) avoid restating the raw facts verbatim.',
+    '',
+    'Observation types (use exactly one per observation):',
+    '- entity_state: the current value of an attribute on an entity, with the latest-known value',
+    '- event_summary: a discrete event or action that happened',
+    '- preference: a stated user preference, opinion, or choice',
+    '- contradiction: two facts in the session that disagree (include both sides)',
+    '- decision: a user decision made during the session',
+    '- numeric_value: a numeric fact (count, amount, duration, percentage)',
+    '',
+    'REQUIRED FIRST OBSERVATION — topic inventory:',
+    'Always emit FIRST an event_summary observation whose text BEGINS with "TOPIC_INVENTORY: " followed by a comma-separated list of the 3–8 distinct top-level concerns/topics/features discussed in this session. GROUP related items into broad categories (e.g. "error handling for 404", "error handling for 401", and "retry logic" → ONE category "API error handling"). The count of items in this list will be used to answer "how many distinct X did I mention" questions, so prefer the smallest reasonable number of broad categories. Cite all relevant memory_ids as evidence.',
+    '',
+    'Output 5–15 observations TOTAL (including the required topic inventory). Call the record_observations tool.',
+].join('\n');
+export const REFLECT_TOOL_SCHEMA = {
+    name: 'record_observations',
+    description: 'Persist the consolidated observations for this conversation.',
+    input_schema: {
+        type: 'object',
+        properties: {
+            observations: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    required: ['text', 'type', 'evidence_memory_ids'],
+                    properties: {
+                        text: { type: 'string' },
+                        type: {
+                            type: 'string',
+                            enum: [
+                                'entity_state', 'event_summary', 'preference',
+                                'contradiction', 'decision', 'numeric_value',
+                            ],
+                        },
+                        evidence_memory_ids: {
+                            type: 'array',
+                            items: { type: 'string' },
+                        },
+                    },
+                },
+            },
+        },
+        required: ['observations'],
+    },
+};
+export function buildReflectMessages(memories) {
+    const lines = memories.map(m => `[${m.id}] (${m.observedAt.toISOString().slice(0, 10)}) ${m.text}`);
+    const user = ['Memories from this conversation (chronological):', '', ...lines].join('\n');
+    return { system: SYSTEM_PROMPT, user };
+}
+const ENTITY_CARD_SYSTEM_PROMPT = (entityName) => [
+    `You maintain a durable summary card for entity "${entityName}".`,
+    '',
+    'The card is read by an answer LLM that must respond to questions about this entity',
+    'across multiple sessions without re-retrieving raw memories. The card must be',
+    'self-contained, dated where relevant, and capture:',
+    '- identity',
+    '- current_values (latest known values)',
+    '- preferences',
+    '- decisions',
+    '- contradictions (both sides if any)',
+    '- open_threads',
+    '',
+    'Hard limit: 250 tokens. Prefer short bulleted lines over prose.',
+].join('\n');
+/**
+ * Assemble the messages for an entity-card synthesis call. The model sees the
+ * prior card (if any) and a list of new observations citing their obs_ids
+ * and dates, and is asked to output ONLY the updated card text.
+ */
+export function buildEntityCardMessages(entityName, priorCardText, observations) {
+    const obsLines = observations.map(o => `[${o.id}] (${o.observedAt.toISOString().slice(0, 10)}) ${o.text}`);
+    const user = [
+        'Prior card:',
+        priorCardText && priorCardText.trim().length > 0 ? priorCardText : '(none)',
+        '',
+        'New observations:',
+        ...obsLines,
+        '',
+        'Output ONLY the updated card text. No preamble.',
+    ].join('\n');
+    return { system: ENTITY_CARD_SYSTEM_PROMPT(entityName), user };
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Query-time reflection retrieval. When the question classifier returns one of
+ * the "synthesis-heavy" types (summary, contradiction, preference, ...), this
+ * module embeds the query and pulls top-K reflections by cosine similarity.
+ * The result is later emitted as a ## OBSERVATIONS prompt channel by
+ * retrieval-format.ts.
+ *
+ * Returns [] when disabled or when the question type is OTHER — the caller
+ * passes the empty array through and downstream packaging emits no
+ * observations block.
+ */
+import type { Reflection, ReflectionsRepository } from '../db/reflections-repository.js';
+import { QuestionType } from './answer-format.js';
+export interface ReflectRetrievalDeps {
+    reflections: Pick<ReflectionsRepository, 'findSimilar'>;
+    embed: (text: string) => Promise<number[]>;
+    topK: number;
+    enabled: boolean;
+}
+/**
+ * Fetch reflections most similar to a user query by cosine similarity.
+ *
+ * When `enabled` is false, returns []. When the question type is OTHER or
+ * ABSTAIN, returns [] (no routing). Otherwise embeds the query and calls
+ * findSimilar on the session_reflections table.
+ *
+ * @param deps DI container with reflections repo, embeddings fn, config
+ * @param userId User ID for scoping the reflection query
+ * @param query Raw user question string to embed
+ * @param questionType Classified question type from answer-format classifier
+ * @returns Array of Reflection objects, empty if disabled or not routed
+ */
+export declare function fetchReflectionsForQuery(deps: ReflectRetrievalDeps, userId: string, query: string, questionType: QuestionType): Promise<Reflection[]>;

package/dist/services/reflect-retrieval.js

@@ -0,0 +1,30 @@
+import { QuestionType } from './answer-format.js';
+const ROUTED_TYPES = new Set([
+    QuestionType.SUMMARY,
+    QuestionType.CONTRADICTION,
+    QuestionType.PREFERENCE,
+    QuestionType.NUMERIC_COUNT,
+    QuestionType.EXACT_DATE,
+    QuestionType.ORDERED_LIST,
+]);
+/**
+ * Fetch reflections most similar to a user query by cosine similarity.
+ *
+ * When `enabled` is false, returns []. When the question type is OTHER or
+ * ABSTAIN, returns [] (no routing). Otherwise embeds the query and calls
+ * findSimilar on the session_reflections table.
+ *
+ * @param deps DI container with reflections repo, embeddings fn, config
+ * @param userId User ID for scoping the reflection query
+ * @param query Raw user question string to embed
+ * @param questionType Classified question type from answer-format classifier
+ * @returns Array of Reflection objects, empty if disabled or not routed
+ */
+export async function fetchReflectionsForQuery(deps, userId, query, questionType) {
+    if (!deps.enabled)
+        return [];
+    if (!ROUTED_TYPES.has(questionType))
+        return [];
+    const embedding = await deps.embed(query);
+    return deps.reflections.findSimilar(userId, embedding, deps.topK);
+}

package/dist/services/reflect.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Reflect orchestrator. Pulls a conversation's memories, sends them to the
+ * answer-LLM tool-use endpoint with the record_observations schema, embeds
+ * each returned observation, and persists them to session_reflections.
+ *
+ * Also drives the always-on ENTITY_CARD channel: after observations are
+ * persisted, groups them by entity, loads the prior cards for the
+ * conversation, calls the entity-card synthesizer (Sonnet 4.5), and upserts
+ * each resulting card. Entity-card synthesis is gated by
+ * `runtimeConfig.entityCardEnabled` and uses Promise.allSettled to fail
+ * soft on individual entity failures — each rejection is logged.
+ *
+ * Pure dependency-injected — the worker (reflect-jobs) supplies real
+ * implementations; tests supply mocks. No I/O of its own beyond what the
+ * injected dependencies do.
+ */
+import type { ReflectionsRepository, ObservationType } from '../db/reflections-repository.js';
+import type { EntityCardsRepository } from '../db/entity-cards-repository.js';
+import { REFLECT_TOOL_SCHEMA, type ReflectMemoryInput } from './reflect-prompts.js';
+import { type SynthesizeCardsDeps } from './entity-card-synthesis.js';
+export interface ReflectToolOutput {
+    observations: Array<{
+        text: string;
+        type: ObservationType;
+        evidence_memory_ids: string[];
+    }>;
+}
+/** Optional entity-card dependencies; absent when entityCardEnabled is false. */
+export interface ReflectEntityCardDeps {
+    enabled: boolean;
+    repo: EntityCardsRepository;
+    synth: SynthesizeCardsDeps;
+    maxCardsPerSession: number;
+}
+export interface ReflectDeps {
+    fetchMemories: (userId: string, conversationId: string) => Promise<readonly ReflectMemoryInput[]>;
+    llmCallTool: (system: string, user: string, toolSchema: typeof REFLECT_TOOL_SCHEMA) => Promise<ReflectToolOutput>;
+    embed: (text: string) => Promise<number[]>;
+    reflections: Pick<ReflectionsRepository, 'insertMany'>;
+    maxObservations: number;
+    /** Optional always-on ENTITY_CARD channel. When absent, no cards are synthesized. */
+    entityCards?: ReflectEntityCardDeps;
+}
+export interface ReflectResult {
+    count: number;
+    /** Number of entity cards upserted in this run. 0 when entity cards are disabled. */
+    entityCardCount: number;
+}
+export declare function runReflectForConversation(deps: ReflectDeps, userId: string, conversationId: string): Promise<ReflectResult>;

package/dist/services/reflect.js

@@ -0,0 +1,84 @@
+import { buildReflectMessages, REFLECT_TOOL_SCHEMA, } from './reflect-prompts.js';
+import { synthesizeCards, } from './entity-card-synthesis.js';
+export async function runReflectForConversation(deps, userId, conversationId) {
+    const memories = await deps.fetchMemories(userId, conversationId);
+    if (memories.length === 0)
+        return { count: 0, entityCardCount: 0 };
+    const { system, user } = buildReflectMessages(memories);
+    const out = await deps.llmCallTool(system, user, REFLECT_TOOL_SCHEMA);
+    const truncated = out.observations.slice(0, deps.maxObservations);
+    const rows = [];
+    for (const o of truncated) {
+        const embedding = await deps.embed(o.text);
+        rows.push({
+            userId,
+            conversationId,
+            observation: o.text,
+            observationType: o.type,
+            evidenceMemoryIds: o.evidence_memory_ids,
+            embedding,
+        });
+    }
+    await deps.reflections.insertMany(rows);
+    const entityCardCount = await maybeSynthesizeEntityCards(deps.entityCards, userId, conversationId, truncated, rows);
+    return { count: rows.length, entityCardCount };
+}
+/**
+ * Drive the always-on ENTITY_CARD channel. Returns the number of cards
+ * upserted. Fails soft on individual entity synthesis errors (each rejection
+ * is logged via console.error per CLAUDE.md "no silent error catching").
+ */
+async function maybeSynthesizeEntityCards(entityCards, userId, conversationId, truncatedObs, rows) {
+    if (!entityCards || !entityCards.enabled)
+        return 0;
+    void rows; // rows reserved for future provenance threading
+    // Synthetic observation IDs: the reflect insertMany path does not
+    // return persisted IDs in the v1 schema, so we cite the index. Future
+    // work: thread row IDs through repository for full provenance.
+    const obsForCards = truncatedObs.map((o, idx) => ({
+        id: `obs-${idx}`,
+        text: o.text,
+        type: o.type,
+        observedAt: new Date(),
+    }));
+    // BEAM/AMB note: the upstream harness encodes BEAM's conversation_id INTO
+    // user_id (per-conversation isolation). The reflect job's conversationId is
+    // a fresh episodeId per ingest, so cards keyed on it never accumulate across
+    // a conversation's many ingests. Scope entity-cards by userId on both sides:
+    // write and read both use userId as the conversation key so cards build up
+    // across the lifetime of the conversation. Outside the BEAM benchmark this
+    // still gives per-conversation scoping because consumers pass conversation-
+    // unique userIds via the AtomicMemory v1 API.
+    void conversationId;
+    const cardScope = userId;
+    const priorCards = await loadPriorCards(entityCards, userId, cardScope);
+    const cards = await synthesizeCards(obsForCards, priorCards, entityCards.synth);
+    const settled = await Promise.allSettled(cards.map((card) => entityCards.repo.upsert({
+        userId,
+        conversationId: cardScope,
+        entityName: card.entityName,
+        cardText: card.cardText,
+        sourceObservationIds: card.sourceObservationIds,
+        version: 1, // repo ON CONFLICT increments via entity_cards.version + 1
+    })));
+    let upserted = 0;
+    for (const r of settled) {
+        if (r.status === 'fulfilled')
+            upserted += 1;
+        else
+            console.error('[reflect:entity-card] upsert failed:', r.reason);
+    }
+    return upserted;
+}
+/**
+ * Load prior cards for the conversation and return a (entityName -> cardText)
+ * lookup map. Errors propagate to the caller (entity-card synthesis is
+ * fail-soft at the worker boundary).
+ */
+async function loadPriorCards(entityCards, userId, conversationId) {
+    const prior = await entityCards.repo.findByConversation(userId, conversationId, entityCards.maxCardsPerSession);
+    const map = new Map();
+    for (const p of prior)
+        map.set(p.entityName, p.cardText);
+    return map;
+}

package/dist/services/relative-temporal.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared relative-temporal helpers for deterministic extraction and retrieval.
+ * Converts phrases like "yesterday" or "next month" into explicit anchors
+ * without depending on an LLM.
+ */
+export type RelativeTemporalPrecision = 'day' | 'week' | 'month';
+export interface RelativeTemporalAnchor {
+    eventDate: string;
+    precision: RelativeTemporalPrecision;
+    phrase: string;
+}
+export declare function annotateRelativeTemporalText(text: string, recordedDate: Date): string;
+export declare function extractRelativeTemporalAnchors(text: string, recordedDate: Date): RelativeTemporalAnchor[];
+export declare function containsRelativeTemporalPhrase(text: string): boolean;

package/dist/services/relative-temporal.js

@@ -0,0 +1,163 @@
+/**
+ * Shared relative-temporal helpers for deterministic extraction and retrieval.
+ * Converts phrases like "yesterday" or "next month" into explicit anchors
+ * without depending on an LLM.
+ */
+const WEEKDAY_INDEX = {
+    sunday: 0,
+    monday: 1,
+    tuesday: 2,
+    wednesday: 3,
+    thursday: 4,
+    friday: 5,
+    saturday: 6,
+};
+const RELATIVE_PATTERNS = [
+    {
+        regex: /\bthe day before\b/gi,
+        resolve: (recordedDate) => buildDayAnchor('the day before', shiftDays(recordedDate, -1)),
+    },
+    {
+        regex: /\bday before\b/gi,
+        resolve: (recordedDate) => buildDayAnchor('day before', shiftDays(recordedDate, -1)),
+    },
+    {
+        regex: /\byesterday\b/gi,
+        resolve: (recordedDate) => buildDayAnchor('yesterday', shiftDays(recordedDate, -1)),
+    },
+    {
+        regex: /\btoday\b/gi,
+        resolve: (recordedDate) => buildDayAnchor('today', recordedDate),
+    },
+    {
+        regex: /\btomorrow\b/gi,
+        resolve: (recordedDate) => buildDayAnchor('tomorrow', shiftDays(recordedDate, 1)),
+    },
+    {
+        regex: /\blast week\b/gi,
+        resolve: (recordedDate) => ({
+            eventDate: formatIsoDay(shiftDays(recordedDate, -7)),
+            precision: 'week',
+            phrase: 'last week',
+        }),
+    },
+    ...Object.keys(WEEKDAY_INDEX).map((weekday) => ({
+        regex: new RegExp(`\\blast\\s+${weekday}\\b`, 'gi'),
+        resolve: (recordedDate) => buildDayAnchor(`last ${weekday}`, previousWeekday(recordedDate, WEEKDAY_INDEX[weekday])),
+    })),
+    {
+        regex: /\bthis month\b/gi,
+        resolve: (recordedDate) => ({
+            eventDate: formatIsoMonth(recordedDate),
+            precision: 'month',
+            phrase: 'this month',
+        }),
+    },
+    {
+        regex: /\blast month\b/gi,
+        resolve: (recordedDate) => ({
+            eventDate: formatIsoMonth(shiftMonths(recordedDate, -1)),
+            precision: 'month',
+            phrase: 'last month',
+        }),
+    },
+    {
+        regex: /\bnext month\b/gi,
+        resolve: (recordedDate) => ({
+            eventDate: formatIsoMonth(shiftMonths(recordedDate, 1)),
+            precision: 'month',
+            phrase: 'next month',
+        }),
+    },
+];
+export function annotateRelativeTemporalText(text, recordedDate) {
+    let annotated = text;
+    for (const pattern of RELATIVE_PATTERNS) {
+        annotated = annotated.replace(pattern.regex, (match) => {
+            const anchor = pattern.resolve(recordedDate);
+            return `${match} (${formatAnchorDescriptor(anchor)})`;
+        });
+    }
+    return annotated;
+}
+export function extractRelativeTemporalAnchors(text, recordedDate) {
+    const anchors = [];
+    for (const pattern of RELATIVE_PATTERNS) {
+        const matches = text.match(pattern.regex);
+        if (!matches)
+            continue;
+        for (const _match of matches) {
+            anchors.push(pattern.resolve(recordedDate));
+        }
+    }
+    return dedupeAnchors(anchors);
+}
+export function containsRelativeTemporalPhrase(text) {
+    return RELATIVE_PATTERNS.some((pattern) => {
+        pattern.regex.lastIndex = 0;
+        return pattern.regex.test(text);
+    });
+}
+function buildDayAnchor(phrase, date) {
+    return {
+        eventDate: formatIsoDay(date),
+        precision: 'day',
+        phrase,
+    };
+}
+function formatAnchorDescriptor(anchor) {
+    if (anchor.precision === 'month') {
+        return `in ${formatHumanMonth(anchor.eventDate)}`;
+    }
+    if (anchor.precision === 'week') {
+        return `around ${formatHumanDay(anchor.eventDate)}`;
+    }
+    return `on ${formatHumanDay(anchor.eventDate)}`;
+}
+function dedupeAnchors(anchors) {
+    const unique = new Map();
+    for (const anchor of anchors) {
+        unique.set(`${anchor.phrase}:${anchor.precision}:${anchor.eventDate}`, anchor);
+    }
+    return [...unique.values()];
+}
+function shiftDays(date, days) {
+    const shifted = new Date(date.getTime());
+    shifted.setUTCDate(shifted.getUTCDate() + days);
+    return shifted;
+}
+function shiftMonths(date, months) {
+    const shifted = new Date(date.getTime());
+    shifted.setUTCMonth(shifted.getUTCMonth() + months, 1);
+    return shifted;
+}
+function previousWeekday(date, targetWeekday) {
+    const shifted = new Date(date.getTime());
+    const currentWeekday = shifted.getUTCDay();
+    const delta = (currentWeekday - targetWeekday + 7) % 7 || 7;
+    shifted.setUTCDate(shifted.getUTCDate() - delta);
+    return shifted;
+}
+function formatIsoDay(date) {
+    return date.toISOString().slice(0, 10);
+}
+function formatIsoMonth(date) {
+    return date.toISOString().slice(0, 7);
+}
+function formatHumanDay(isoDay) {
+    const date = new Date(`${isoDay}T00:00:00.000Z`);
+    return date.toLocaleDateString('en-US', {
+        timeZone: 'UTC',
+        month: 'long',
+        day: 'numeric',
+        year: 'numeric',
+    });
+}
+function formatHumanMonth(isoMonth) {
+    const date = new Date(`${isoMonth}-01T00:00:00.000Z`);
+    return date.toLocaleDateString('en-US', {
+        timeZone: 'UTC',
+        month: 'long',
+        year: 'numeric',
+    });
+}

package/dist/services/relevance-policy.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Score semantics and relevance threshold policy for retrieval packaging.
+ */
+import type { SearchResult } from '../db/repository-types.js';
+import { type QueryComplexityLabel } from './retrieval-policy.js';
+export interface RelevanceGateConfig {
+    similarityThreshold: number;
+}
+export interface RelevanceGateContext {
+    asOf?: string;
+    sourceSite?: string;
+}
+export interface RelevanceGate {
+    threshold: number | null;
+    source: 'request' | 'config' | 'disabled';
+    reason: string;
+    queryLabel: QueryComplexityLabel;
+}
+export interface RelevanceFilterDecision {
+    id: string;
+    sourceSite: string;
+    sourceKind: 'integration' | 'local';
+    namespace: string | null;
+    semanticSimilarity: number;
+    rankingScore: number;
+    relevance: number;
+    threshold: number | null;
+    decision: 'kept' | 'filtered';
+    reason: string;
+}
+export interface RelevanceFilterResult {
+    memories: SearchResult[];
+    decisions: RelevanceFilterDecision[];
+    removedIds: string[];
+}
+export declare function resolveRelevanceGate(query: string, requestedThreshold: number | undefined, runtimeConfig: RelevanceGateConfig, context?: RelevanceGateContext): RelevanceGate;
+export declare function applyRelevanceFilter(memories: SearchResult[], gate: RelevanceGate): RelevanceFilterResult;