@atomicmemory/core 1.0.0

package/dist/services/entity-card-synthesis.js

@@ -0,0 +1,92 @@
+/**
+ * Entity-card synthesis (BEAM-0.85 — always-on ENTITY_CARD channel).
+ *
+ * Pure dependency-injected: callers provide `llmCallTool` (typically Sonnet 4.5)
+ * and the prior card lookup. For each entity with at least
+ * `minObservations` new observations in the current Reflect run, the
+ * synthesizer assembles a `buildEntityCardMessages` prompt and calls the
+ * model to produce an updated card. The output for one entity has no
+ * dependency on the output for any other entity — callers parallelize via
+ * Promise.allSettled to fail-soft on individual synthesis errors.
+ *
+ * No silent error catching: errors from `llmCallTool` propagate to the
+ * Promise.allSettled boundary in the caller, which logs each rejection.
+ */
+import { buildEntityCardMessages, } from './reflect-prompts.js';
+/** Schema for the tool-use call that returns the updated card text. */
+const ENTITY_CARD_TOOL_SCHEMA = {
+    name: 'record_entity_card',
+    description: 'Persist the updated entity card text.',
+    input_schema: {
+        type: 'object',
+        properties: { card_text: { type: 'string' } },
+        required: ['card_text'],
+    },
+};
+/**
+ * Group observations by entity_name. The entity is extracted from
+ * entity_state observations whose text begins with "<EntityName>:" or
+ * a leading capitalized noun before the first colon/verb.
+ *
+ * Heuristic (simplified — see compromises in report): the first capitalized
+ * token sequence at the start of the observation text. The literal token
+ * "User" / "user" maps to the canonical entity "user".
+ */
+export function groupObservationsByEntity(observations) {
+    const grouped = new Map();
+    for (const obs of observations) {
+        const entity = extractEntityName(obs);
+        if (!entity)
+            continue;
+        const list = grouped.get(entity) ?? [];
+        list.push(obs);
+        grouped.set(entity, list);
+    }
+    return grouped;
+}
+const USER_PREFIX = /^\s*(user|the user|you)\b/i;
+const CAPITALIZED_PHRASE = /^([A-Z][A-Za-z0-9_-]*(?:\s+[A-Z][A-Za-z0-9_-]*){0,2})\b/;
+function extractEntityName(obs) {
+    // entity_state observations are the strongest signal — but any observation
+    // that starts with a capitalized noun phrase or the literal "user"
+    // contributes to that entity's card.
+    const text = obs.text.trim();
+    if (USER_PREFIX.test(text))
+        return 'user';
+    const m = CAPITALIZED_PHRASE.exec(text);
+    if (m)
+        return m[1].trim();
+    return null;
+}
+/**
+ * Synthesize ENTITY_CARDs for every entity with >= minObservations
+ * observations in the current Reflect run. Prior cards are looked up
+ * by entity_name; absent entities use the empty prior. Returns one
+ * EntityCardSynth per synthesized entity.
+ */
+export async function synthesizeCards(observations, priorCards, deps) {
+    const grouped = groupObservationsByEntity(observations);
+    const eligible = Array.from(grouped.entries())
+        .filter(([, list]) => list.length >= deps.minObservations)
+        .slice(0, deps.maxEntities);
+    const results = [];
+    for (const [entityName, list] of eligible) {
+        const obsInputs = list.map(o => ({
+            id: o.id,
+            text: o.text,
+            observedAt: o.observedAt,
+        }));
+        const priorText = priorCards.get(entityName) ?? null;
+        const { system, user } = buildEntityCardMessages(entityName, priorText, obsInputs);
+        const out = await deps.llmCallTool(system, user, ENTITY_CARD_TOOL_SCHEMA);
+        const cardText = (out.card_text ?? '').trim();
+        if (!cardText)
+            continue;
+        results.push({
+            entityName,
+            cardText,
+            sourceObservationIds: list.map(o => o.id),
+        });
+    }
+    return results;
+}

package/dist/services/entity-dedup.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared entity deduplication utility.
+ *
+ * Placed in its own module to avoid extending the circular dependency between
+ * extraction.ts, extraction-enrichment.ts, and event-anchor-facts.ts.
+ */
+import type { ExtractedEntity } from './extraction.js';
+/** Deduplicate entities by type+lowered-name key. */
+export declare function dedupeEntities(entities: ExtractedEntity[]): ExtractedEntity[];

package/dist/services/entity-dedup.js

@@ -0,0 +1,14 @@
+/**
+ * Shared entity deduplication utility.
+ *
+ * Placed in its own module to avoid extending the circular dependency between
+ * extraction.ts, extraction-enrichment.ts, and event-anchor-facts.ts.
+ */
+/** Deduplicate entities by type+lowered-name key. */
+export function dedupeEntities(entities) {
+    const unique = new Map();
+    for (const entity of entities) {
+        unique.set(`${entity.type}:${entity.name.toLowerCase()}`, entity);
+    }
+    return [...unique.values()];
+}

package/dist/services/entity-graph.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Entity co-occurrence graph for spreading activation retrieval.
+ *
+ * At ingest time: extract entities from fact text, store pairwise co-occurrence edges.
+ * At query time: extract query entities, run 3-hop spreading activation, score memories
+ * by accumulated activation. Returns ranked memory IDs for RRF fusion with vector search.
+ */
+export interface EntityGraphResult {
+    memoryId: string;
+    activationScore: number;
+}
+/**
+ * Extract entities from text for graph construction.
+ * Captures: proper nouns (capitalized words), technology names, multi-word terms.
+ * Returns normalized lowercase entities.
+ */
+export declare function extractEntities(text: string): string[];

package/dist/services/entity-graph.js

@@ -0,0 +1,135 @@
+/**
+ * Entity co-occurrence graph for spreading activation retrieval.
+ *
+ * At ingest time: extract entities from fact text, store pairwise co-occurrence edges.
+ * At query time: extract query entities, run 3-hop spreading activation, score memories
+ * by accumulated activation. Returns ranked memory IDs for RRF fusion with vector search.
+ */
+import { storeEntityEdges, findNeighbors, findMemoriesForEntities, removeEntityEdges as removeEdges, } from '../db/repository-entity-graph.js';
+/** Spreading activation parameters (SLM-V3: γ=0.7, maxHops=3). */
+const ACTIVATION_DECAY = 0.7;
+const MAX_HOPS = 3;
+const ACTIVATION_THRESHOLD = 0.01;
+/** Minimum entity length for graph inclusion. */
+const MIN_ENTITY_LENGTH = 3;
+/**
+ * Stopwords excluded from entity extraction.
+ * Broader than AUDN conflict keywords — filters common verbs, prepositions, articles.
+ */
+const STOPWORDS = new Set([
+    'the', 'and', 'for', 'that', 'this', 'with', 'from', 'have', 'has', 'had',
+    'was', 'were', 'been', 'being', 'will', 'would', 'could', 'should', 'might',
+    'also', 'just', 'about', 'into', 'over', 'after', 'before', 'between',
+    'through', 'during', 'each', 'other', 'some', 'such', 'than', 'then',
+    'these', 'those', 'when', 'where', 'which', 'while', 'their', 'there',
+    'they', 'them', 'what', 'who', 'how', 'very', 'more', 'most', 'only',
+    'same', 'does', 'doing', 'done', 'using', 'used', 'uses', 'user',
+    'like', 'want', 'wants', 'make', 'made', 'making', 'work', 'working',
+    'plan', 'plans', 'planning', 'currently', 'recently', 'project',
+    'maybe', 'might', 'perhaps', 'check', 'tomorrow', 'sure', 'think',
+    'not',
+]);
+/**
+ * Extract entities from text for graph construction.
+ * Captures: proper nouns (capitalized words), technology names, multi-word terms.
+ * Returns normalized lowercase entities.
+ */
+export function extractEntities(text) {
+    const entities = new Set();
+    const words = text.match(/[A-Za-z][A-Za-z0-9._-]*/g) ?? [];
+    for (const word of words) {
+        const lower = word.toLowerCase();
+        if (lower.length < MIN_ENTITY_LENGTH)
+            continue;
+        if (STOPWORDS.has(lower))
+            continue;
+        entities.add(lower);
+    }
+    const compoundPatterns = [
+        /[A-Z][a-z]+(?:\s+[A-Z][a-z]+)+/g,
+        /[A-Za-z]+[._-][A-Za-z]+/g,
+    ];
+    for (const pattern of compoundPatterns) {
+        const matches = text.match(pattern) ?? [];
+        for (const match of matches) {
+            const normalized = match.toLowerCase().replace(/\s+/g, '_');
+            if (normalized.length >= MIN_ENTITY_LENGTH) {
+                entities.add(normalized);
+            }
+        }
+    }
+    return [...entities];
+}
+/** Update entity graph after storing a new memory. */
+async function updateEntityGraph(pool, userId, memoryId, factText) {
+    const entities = extractEntities(factText);
+    return storeEntityEdges(pool, userId, memoryId, entities);
+}
+/** Replace entity graph edges for a memory (used on UPDATE/SUPERSEDE). */
+async function replaceEntityEdges(pool, userId, memoryId, factText) {
+    await removeEdges(pool, memoryId);
+    return updateEntityGraph(pool, userId, memoryId, factText);
+}
+/**
+ * 3-hop spreading activation from query entities.
+ * Returns memories scored by accumulated activation, sorted descending.
+ *
+ * Algorithm:
+ * 1. Seed activation map with query entities (activation=1.0)
+ * 2. For each hop: find neighbors, propagate activation * γ
+ * 3. Collect all activated entities, find linked memories
+ * 4. Score each memory by sum of activations from its linked entities
+ */
+async function spreadingActivation(pool, userId, queryText, limit) {
+    const queryEntities = extractEntities(queryText);
+    if (queryEntities.length === 0)
+        return [];
+    const activation = seedActivationMap(queryEntities);
+    await propagateActivation(pool, userId, activation);
+    return scoreMemoriesByActivation(pool, userId, activation, limit);
+}
+/** Initialize activation map with query entities at full activation. */
+function seedActivationMap(entities) {
+    const activation = new Map();
+    for (const entity of entities) {
+        activation.set(entity, 1.0);
+    }
+    return activation;
+}
+/** Propagate activation through the entity graph for MAX_HOPS iterations. */
+async function propagateActivation(pool, userId, activation) {
+    for (let hop = 0; hop < MAX_HOPS; hop++) {
+        const activeEntities = [...activation.entries()]
+            .filter(([, score]) => score >= ACTIVATION_THRESHOLD)
+            .map(([entity]) => entity);
+        if (activeEntities.length === 0)
+            break;
+        const neighbors = await findNeighbors(pool, userId, activeEntities);
+        for (const neighbor of neighbors) {
+            const sourceActivation = activation.get(neighbor.entity) ?? 0;
+            if (sourceActivation < ACTIVATION_THRESHOLD)
+                continue;
+            const propagated = sourceActivation * ACTIVATION_DECAY;
+            const existing = activation.get(neighbor.entity) ?? 0;
+            activation.set(neighbor.entity, Math.max(existing, propagated));
+        }
+    }
+}
+/** Score memories by summing activation from their linked entities. */
+async function scoreMemoriesByActivation(pool, userId, activation, limit) {
+    const allActivatedEntities = [...activation.entries()]
+        .filter(([, score]) => score >= ACTIVATION_THRESHOLD)
+        .map(([entity]) => entity);
+    if (allActivatedEntities.length === 0)
+        return [];
+    const memoryEntities = await findMemoriesForEntities(pool, userId, allActivatedEntities);
+    const memoryScores = new Map();
+    for (const { memoryId, entity } of memoryEntities) {
+        const current = memoryScores.get(memoryId) ?? 0;
+        memoryScores.set(memoryId, current + (activation.get(entity) ?? 0));
+    }
+    return [...memoryScores.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, limit)
+        .map(([memoryId, activationScore]) => ({ memoryId, activationScore }));
+}

package/dist/services/entropy-gate.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Entropy-Aware Write Gating.
+ *
+ * Filters low-information writes before they reach the memory store.
+ * A candidate memory is discarded if its entropy score falls below
+ * ENTROPY_THRESHOLD (default 0.35), meaning it adds little novel
+ * information relative to what's already stored.
+ *
+ * Entropy score combines two signals:
+ *   - Entity novelty: ratio of new entities to total entities in the text
+ *   - Semantic novelty: cosine distance from the previous context embedding
+ *
+ * Source: SimpleMem pattern (entropy-aware gating at threshold 0.35).
+ */
+import { cosineSimilarity } from '../vector-math.js';
+export interface EntropyGateConfig {
+    threshold: number;
+    alpha: number;
+}
+export declare const DEFAULT_ENTROPY_CONFIG: EntropyGateConfig;
+export interface EntropyInput {
+    /** Entities extracted from the candidate text. */
+    windowEntities: string[];
+    /** Entities already known from existing memories. */
+    existingEntities: Set<string>;
+    /** Embedding of the candidate text. */
+    windowEmbedding: number[];
+    /** Embedding of the previous context window (null if first). */
+    previousEmbedding: number[] | null;
+}
+export interface EntropyResult {
+    score: number;
+    entityNovelty: number;
+    semanticNovelty: number;
+    accepted: boolean;
+}
+/**
+ * Compute the entropy score for a candidate memory.
+ * Score = α × entityNovelty + (1-α) × semanticNovelty.
+ */
+export declare function computeEntropyScore(input: EntropyInput, config?: EntropyGateConfig): EntropyResult;
+/**
+ * Ratio of new (unseen) entities to total entities in the window.
+ * Returns 1.0 if no entities are present (assume novel).
+ */
+export declare function computeEntityNovelty(windowEntities: string[], existingEntities: Set<string>): number;
+/**
+ * Semantic distance from previous context embedding.
+ * Returns 1.0 if no previous embedding exists (assume fully novel).
+ */
+export declare function computeSemanticNovelty(current: number[], previous: number[] | null): number;
+export { cosineSimilarity };

package/dist/services/entropy-gate.js

@@ -0,0 +1,56 @@
+/**
+ * Entropy-Aware Write Gating.
+ *
+ * Filters low-information writes before they reach the memory store.
+ * A candidate memory is discarded if its entropy score falls below
+ * ENTROPY_THRESHOLD (default 0.35), meaning it adds little novel
+ * information relative to what's already stored.
+ *
+ * Entropy score combines two signals:
+ *   - Entity novelty: ratio of new entities to total entities in the text
+ *   - Semantic novelty: cosine distance from the previous context embedding
+ *
+ * Source: SimpleMem pattern (entropy-aware gating at threshold 0.35).
+ */
+import { cosineSimilarity } from '../vector-math.js';
+const DEFAULT_ENTROPY_THRESHOLD = 0.35;
+const DEFAULT_ALPHA = 0.5;
+export const DEFAULT_ENTROPY_CONFIG = {
+    threshold: DEFAULT_ENTROPY_THRESHOLD,
+    alpha: DEFAULT_ALPHA,
+};
+/**
+ * Compute the entropy score for a candidate memory.
+ * Score = α × entityNovelty + (1-α) × semanticNovelty.
+ */
+export function computeEntropyScore(input, config = DEFAULT_ENTROPY_CONFIG) {
+    const entityNovelty = computeEntityNovelty(input.windowEntities, input.existingEntities);
+    const semanticNovelty = computeSemanticNovelty(input.windowEmbedding, input.previousEmbedding);
+    const score = config.alpha * entityNovelty + (1 - config.alpha) * semanticNovelty;
+    return {
+        score,
+        entityNovelty,
+        semanticNovelty,
+        accepted: score >= config.threshold,
+    };
+}
+/**
+ * Ratio of new (unseen) entities to total entities in the window.
+ * Returns 1.0 if no entities are present (assume novel).
+ */
+export function computeEntityNovelty(windowEntities, existingEntities) {
+    if (windowEntities.length === 0)
+        return 1.0;
+    const newCount = windowEntities.filter((e) => !existingEntities.has(e)).length;
+    return newCount / windowEntities.length;
+}
+/**
+ * Semantic distance from previous context embedding.
+ * Returns 1.0 if no previous embedding exists (assume fully novel).
+ */
+export function computeSemanticNovelty(current, previous) {
+    if (!previous || previous.length === 0)
+        return 1.0;
+    return 1 - cosineSimilarity(current, previous);
+}
+export { cosineSimilarity };

package/dist/services/episode-fetcher.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Injection-channel fetchers (Sprint 3 v1.5 H2 + v1.6 H4 from haiku-080).
+ *
+ * Extracted from memory-search.ts to keep that orchestrator under the
+ * 400-line cap. Owns the side-channel reads (user-profile + recap top-K)
+ * that surface as dedicated prompt sections (`## USER PROFILE`,
+ * `## EPISODES`) above the standard `<atomicmem_context>` body.
+ *
+ * The episodes channel is the alternative to routing recaps through the
+ * RRF fan-in — recap rows surface to the answer LLM in their own prompt
+ * section instead of displacing atomic facts in top-K.
+ */
+import type { MemoryServiceDeps } from './memory-service-types.js';
+import type { EpisodeForInjection } from './retrieval-format.js';
+/**
+ * Fetch the recap-store top-K rows for the given query embedding when the
+ * episodes channel flag is on. Returns `[]` whenever the flag is off, the
+ * recap store is absent, or no candidates are found.
+ */
+export declare function fetchEpisodesForInjection(deps: MemoryServiceDeps, userId: string, queryEmbedding: number[]): Promise<EpisodeForInjection[]>;
+/**
+ * Fetch the pinned user-profile document (Sprint 3 v1.5 — H2). Returns
+ * `undefined` when the channel flag is off, the store is null, or no profile
+ * row exists for the user. Fail-soft: log + treat as absent on read errors,
+ * never block the search path.
+ */
+export declare function fetchUserProfileText(deps: MemoryServiceDeps, userId: string): Promise<string | undefined>;
+/**
+ * Entity-attribute triple promoted into the injection's `## FACTS` channel
+ * (Sprint 4 EAI — Task C). Reaches the answer LLM as a pinned line above
+ * the standard memories body so atomic facts survive the top-K cutoff.
+ */
+export interface EntityFactForInjection {
+    entity: string;
+    attribute: string;
+    value: string;
+    observedAt: Date;
+}
+/**
+ * Fetch entity-attribute triples likely relevant to the query. Heuristic:
+ * extract nouns + numerics + attribute-like tokens from the query, look them
+ * up in the EAI by entity_name OR attribute_key match. Returns most-recent
+ * first. Fail-soft: returns [] on any error so the search path never breaks.
+ */
+export declare function fetchEntityFactsForInjection(deps: MemoryServiceDeps, userId: string, query: string): Promise<EntityFactForInjection[]>;
+/** Tokenize the query into lookup-worthy strings. */
+export declare function extractLookupTokens(query: string): string[];

package/dist/services/episode-fetcher.js

@@ -0,0 +1,128 @@
+/**
+ * Injection-channel fetchers (Sprint 3 v1.5 H2 + v1.6 H4 from haiku-080).
+ *
+ * Extracted from memory-search.ts to keep that orchestrator under the
+ * 400-line cap. Owns the side-channel reads (user-profile + recap top-K)
+ * that surface as dedicated prompt sections (`## USER PROFILE`,
+ * `## EPISODES`) above the standard `<atomicmem_context>` body.
+ *
+ * The episodes channel is the alternative to routing recaps through the
+ * RRF fan-in — recap rows surface to the answer LLM in their own prompt
+ * section instead of displacing atomic facts in top-K.
+ */
+/** Lower/upper bounds on the recap top-K, to keep the channel signal tight. */
+const EPISODES_TOP_K_MIN = 1;
+const EPISODES_TOP_K_MAX = 5;
+/**
+ * Fetch the recap-store top-K rows for the given query embedding when the
+ * episodes channel flag is on. Returns `[]` whenever the flag is off, the
+ * recap store is absent, or no candidates are found.
+ */
+export async function fetchEpisodesForInjection(deps, userId, queryEmbedding) {
+    if (!deps.config.episodesChannelEnabled)
+        return [];
+    const recapStore = deps.stores.recap;
+    if (!recapStore)
+        return [];
+    const k = clampTopK(deps.config.episodesChannelTopK);
+    try {
+        const candidates = await recapStore.findRecapCandidates(userId, queryEmbedding, k);
+        return candidates.map((row) => ({
+            topic: row.topic,
+            narrative: row.recap_text,
+        }));
+    }
+    catch (err) {
+        console.warn(`[episodes] fetch failed for user=${userId}: ${err.message}`);
+        return [];
+    }
+}
+/**
+ * Fetch the pinned user-profile document (Sprint 3 v1.5 — H2). Returns
+ * `undefined` when the channel flag is off, the store is null, or no profile
+ * row exists for the user. Fail-soft: log + treat as absent on read errors,
+ * never block the search path.
+ */
+export async function fetchUserProfileText(deps, userId) {
+    if (!deps.config.userProfileChannelEnabled)
+        return undefined;
+    const profileStore = deps.stores.userProfile;
+    if (!profileStore)
+        return undefined;
+    try {
+        const row = await profileStore.getProfile(userId);
+        if (row?.profile_text)
+            return row.profile_text;
+        return undefined;
+    }
+    catch (err) {
+        console.warn(`[profile] fetch failed for user=${userId}: ${err.message}`);
+        return undefined;
+    }
+}
+function clampTopK(requested) {
+    if (!Number.isFinite(requested))
+        return EPISODES_TOP_K_MIN;
+    return Math.max(EPISODES_TOP_K_MIN, Math.min(EPISODES_TOP_K_MAX, Math.floor(requested)));
+}
+/** Lower/upper bounds on EAI lookup top-K; mirrors the channel-pattern. */
+const EAI_TOP_K_MIN = 5;
+const EAI_TOP_K_MAX = 40;
+/**
+ * Fetch entity-attribute triples likely relevant to the query. Heuristic:
+ * extract nouns + numerics + attribute-like tokens from the query, look them
+ * up in the EAI by entity_name OR attribute_key match. Returns most-recent
+ * first. Fail-soft: returns [] on any error so the search path never breaks.
+ */
+export async function fetchEntityFactsForInjection(deps, userId, query) {
+    if (!deps.config.entityAttributesEnabled)
+        return [];
+    const repo = deps.stores.entityAttributes;
+    if (!repo)
+        return [];
+    const tokens = extractLookupTokens(query);
+    if (tokens.length === 0)
+        return [];
+    try {
+        const limit = clampEaiTopK(deps.config.entityAttributesTopK);
+        const rows = await repo.findByEntityOrAttribute(userId, tokens, limit);
+        return rows.map((r) => ({
+            entity: r.entity_name,
+            attribute: r.attribute_key,
+            value: r.attribute_value,
+            observedAt: r.observed_at,
+        }));
+    }
+    catch (err) {
+        console.warn(`[eai] fetch failed user=${userId}: ${err.message}`);
+        return [];
+    }
+}
+function clampEaiTopK(requested) {
+    const value = requested ?? 20;
+    if (!Number.isFinite(value))
+        return EAI_TOP_K_MIN;
+    return Math.max(EAI_TOP_K_MIN, Math.min(EAI_TOP_K_MAX, Math.floor(value)));
+}
+/**
+ * Tokenizer-stopwords for the EAI query→lookup heuristic. Conservative list —
+ * drops question-frame words and tiny connectives but keeps domain nouns
+ * (e.g. "problems", "features", "columns") so they can match `entity_name`
+ * or `attribute_key` rows in the EAI.
+ */
+const STOP_TOKENS = new Set([
+    'the', 'a', 'an', 'of', 'in', 'on', 'at', 'to', 'for', 'and', 'or', 'is', 'are', 'was', 'were', 'my', 'your',
+    'i', 'you', 'we', 'they', 'what', 'which', 'when', 'where', 'how', 'many', 'much', 'do', 'did', 'have', 'has',
+    'had', 'this', 'that', 'these', 'those', 'it', 'its', 'about', 'any', 'some', 'all', 'can', 'could', 'would',
+    'should', 'will', 'please', 'tell', 'me', 'show', 'across', 'between', 'from', 'with', 'if',
+    'over', 'under', 'same', 'different', 'specific', 'only', 'just', 'simply', 'really', 'very', 'also', 'too',
+]);
+const EAI_TOKEN_MAX = 8;
+const EAI_TOKEN_MIN_LENGTH = 3;
+/** Tokenize the query into lookup-worthy strings. */
+export function extractLookupTokens(query) {
+    const words = (query.toLowerCase().match(/[a-z][a-z0-9_-]+/g) ?? []).filter((w) => w.length >= EAI_TOKEN_MIN_LENGTH && !STOP_TOKENS.has(w));
+    const numbers = query.match(/\b\d+\b/g) ?? [];
+    // Deduplicate, cap at EAI_TOKEN_MAX to keep SQL parameter list small.
+    return Array.from(new Set([...words, ...numbers])).slice(0, EAI_TOKEN_MAX);
+}

package/dist/services/event-anchor-facts.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Deterministic event-anchor fact generation for Cat2-style disambiguation.
+ * Converts high-signal extracted facts into explicit event memories such as
+ * "event anchor mentorship.received for Jon occurred on June 15 2023" so
+ * retrieval and answer-time prompting can rely on structured event labels.
+ */
+import type { ExtractedFact } from './extraction.js';
+export declare function inferEventAnchorFacts(fact: ExtractedFact): ExtractedFact[];