@atomicmemory/core 1.0.0

package/dist/services/temporal-endpoint-evidence.js

@@ -0,0 +1,313 @@
+/**
+ * Query-aware temporal evidence formatting.
+ *
+ * Produces compact date-bearing evidence blocks for temporal questions. For
+ * repeated-event comparisons it emits explicit first/second endpoints; for
+ * broader temporal questions it emits a small set of high-overlap candidate
+ * memories with their dates.
+ */
+import { formatDateLabel, formatDuration } from './temporal-format.js';
+const REPEATED_EVENT_QUERY = /\bbetween\b[\s\S]*\bfirst\b[\s\S]*\bsecond\b|\bfirst\b[\s\S]*\bsecond\b/i;
+const TEMPORAL_QUERY = /\b(when|how long|how many months|how many years|how many weeks|how many days|between|before|after|as of|recently)\b/i;
+const DURATION_QUERY = /\b(how long|how many months|how many years|how many weeks|how many days|between|before|after)\b/i;
+const EVIDENCE_MAX_CHARS = 160;
+const QUERY_TERM_MIN_LENGTH = 4;
+const GENERAL_TEMPORAL_LIMIT = 3;
+const STEM_SUFFIXES = ['ing', 'ed', 'es', 's'];
+const SUBJECT_MATCH_BONUS = 2;
+const EVENT_GROUP_MATCH_BONUS = 2;
+const PLANNING_PENALTY = 3;
+const DURATION_ENDPOINT_LIMIT = 2;
+const PLANNING_MARKERS = [
+    'plan to', 'planned to', 'planning to', 'going to', 'will ', 'wants to',
+    'want to', 'thinking of', 'thinking about', 'considering', 'decided to make',
+    'make a new appointment', 'book a new appointment',
+];
+const QUERY_SUBJECT_STOP_WORDS = new Set([
+    'When', 'What', 'Where', 'Why', 'How', 'Who', 'Which',
+    'Did', 'Does', 'Do', 'Has', 'Have', 'Had',
+    'The', 'A', 'An', 'As', 'Of', 'And', 'Or',
+    'First', 'Second',
+]);
+const MONTH_NAMES = new Set([
+    'January', 'February', 'March', 'April', 'May', 'June',
+    'July', 'August', 'September', 'October', 'November', 'December',
+]);
+const QUERY_EVENT_STOP_WORDS = new Set([
+    'between', 'first', 'second', 'months', 'month', 'weeks', 'week',
+    'days', 'many', 'much', 'long', 'lapsed', 'elapsed', 'passed',
+    'what', 'when', 'where', 'which', 'with', 'from', 'that', 'this',
+    'before', 'after', 'recently', 'start', 'started', 'plan', 'planned',
+    'recent', 'current', 'present', 'did', 'does', 'have', 'been',
+]);
+const EVENT_SYNONYMS = {
+    appointment: ['appointment', 'appointments', 'check-up', 'checkup', 'check up', 'visit'],
+    doctor: ['doctor', "doctor's", 'doctors', 'doc', 'medical', 'health'],
+};
+const IRREGULAR_NORMALIZATION = {
+    won: 'win',
+    winning: 'win',
+    met: 'meet',
+    meeting: 'meet',
+    began: 'begin',
+    begun: 'begin',
+    started: 'start',
+    starting: 'start',
+    moved: 'move',
+    moving: 'move',
+    dated: 'date',
+    dating: 'date',
+    adopted: 'adopt',
+    adopting: 'adopt',
+    adoption: 'adopt',
+    expanded: 'expand',
+    expanding: 'expand',
+    presence: 'present',
+};
+/** Reverse index: each synonym → its canonical key. Built once at module load. */
+const SYNONYM_TO_CANONICAL = (() => {
+    const index = new Map();
+    for (const [canonical, synonyms] of Object.entries(EVENT_SYNONYMS)) {
+        for (const synonym of synonyms)
+            index.set(synonym, canonical);
+    }
+    return index;
+})();
+export function buildTemporalEvidenceBlock(memories, query) {
+    const repeatedEventBlock = buildRepeatedEventEndpointBlock(memories, query);
+    if (repeatedEventBlock)
+        return repeatedEventBlock;
+    return buildGeneralTemporalEvidenceBlock(memories, query);
+}
+/** Build endpoint lines for repeated-event temporal comparisons. */
+export function buildRepeatedEventEndpointBlock(memories, query) {
+    if (!isRepeatedEventQuery(query))
+        return '';
+    const conceptGroups = extractEventConceptGroups(query);
+    if (conceptGroups.length === 0)
+        return '';
+    const candidates = findEndpointCandidates(memories, conceptGroups);
+    const endpoints = selectDistinctDateEndpoints(candidates);
+    if (endpoints.length < 2)
+        return '';
+    const [first, second] = endpoints;
+    const days = diffDays(first.memory.created_at, second.memory.created_at);
+    return [
+        'Repeated event endpoints:',
+        formatEndpointLine('first matching event', first),
+        formatEndpointLine('second matching event', second),
+        `- elapsed between endpoints: ${formatDuration(days)}`,
+    ].join('\n');
+}
+function isRepeatedEventQuery(query) {
+    return REPEATED_EVENT_QUERY.test(query.toLowerCase());
+}
+function buildGeneralTemporalEvidenceBlock(memories, query) {
+    if (!TEMPORAL_QUERY.test(query.toLowerCase()))
+        return '';
+    const queryTerms = extractGeneralTemporalTerms(query);
+    const subjectTerms = extractQuerySubjects(query);
+    const conceptGroups = extractEventConceptGroups(query);
+    if (queryTerms.length === 0)
+        return '';
+    const candidates = selectGeneralTemporalCandidates(memories, queryTerms, subjectTerms, conceptGroups);
+    if (candidates.length === 0)
+        return '';
+    const endpointLines = buildGeneralDurationEndpointLines(candidates, query);
+    if (endpointLines.length > 0) {
+        return ['Temporal evidence candidates:', ...endpointLines].join('\n');
+    }
+    return [
+        'Temporal evidence candidates:',
+        ...candidates.map((candidate) => formatEndpointLine('matching event', candidate)),
+    ].join('\n');
+}
+/**
+ * Extract one ConceptGroup per distinct canonical event term in the query.
+ * Plural and synonym forms collapse to the same group via SYNONYM_TO_CANONICAL;
+ * unknown terms become singleton groups.
+ */
+function extractEventConceptGroups(query) {
+    const source = extractOrdinalClauses(query);
+    const rawTerms = extractTemporalTerms(source);
+    const seenCanonicals = new Set();
+    const groups = [];
+    for (const term of rawTerms) {
+        const canonical = SYNONYM_TO_CANONICAL.get(term);
+        if (canonical) {
+            if (!seenCanonicals.has(canonical)) {
+                seenCanonicals.add(canonical);
+                groups.push(EVENT_SYNONYMS[canonical]);
+            }
+        }
+        else {
+            groups.push([term]);
+        }
+    }
+    return groups;
+}
+function extractOrdinalClauses(query) {
+    const pieces = query.toLowerCase().split(/\b(?:first|second)\b/).slice(1);
+    return pieces.join(' ') || query;
+}
+function extractGeneralTemporalTerms(query) {
+    return extractTemporalTerms(query);
+}
+function extractTemporalTerms(query) {
+    return query
+        .toLowerCase()
+        .replace(/\b([a-z]+)'s\b/g, '$1')
+        .replace(/[^a-z0-9'\s-]/g, ' ')
+        .split(/\s+/)
+        .filter((term) => term.length >= QUERY_TERM_MIN_LENGTH)
+        .filter((term) => !QUERY_EVENT_STOP_WORDS.has(term));
+}
+function extractQuerySubjects(query) {
+    const subjectMatches = query.match(/\b[A-Z][a-z]+(?:'s)?\b/g) ?? [];
+    const normalized = subjectMatches
+        .map((subject) => subject.replace(/'s$/i, ''))
+        .filter((subject) => !QUERY_SUBJECT_STOP_WORDS.has(subject))
+        .filter((subject) => !MONTH_NAMES.has(subject));
+    return [...new Set(normalized.map((subject) => subject.toLowerCase()))];
+}
+function findEndpointCandidates(memories, conceptGroups) {
+    return memories
+        .map((memory) => scoreEndpointCandidate(memory, conceptGroups))
+        .filter((candidate) => candidate !== null)
+        .sort((left, right) => left.memory.created_at.getTime() - right.memory.created_at.getTime());
+}
+function selectGeneralTemporalCandidates(memories, queryTerms, subjectTerms, conceptGroups) {
+    return memories
+        .map((memory) => scoreGeneralTemporalCandidate(memory, queryTerms, subjectTerms, conceptGroups))
+        .filter((candidate) => candidate !== null)
+        .sort((left, right) => compareGeneralTemporalCandidates(left, right))
+        .slice(0, GENERAL_TEMPORAL_LIMIT);
+}
+/**
+ * A candidate qualifies only if every concept group in the query has at
+ * least one synonym present in the memory's content. Score is the number
+ * of groups matched (ties broken by date order downstream).
+ */
+function scoreEndpointCandidate(memory, conceptGroups) {
+    const content = memory.content.toLowerCase();
+    const matched = conceptGroups.filter((group) => group.some((synonym) => content.includes(synonym))).length;
+    if (matched < conceptGroups.length)
+        return null;
+    return { dateKey: formatDateLabel(memory.created_at), memory, score: matched };
+}
+function scoreGeneralTemporalCandidate(memory, queryTerms, subjectTerms, conceptGroups) {
+    const lowerContent = memory.content.toLowerCase();
+    const tokenSet = buildNormalizedTokenSet(memory.content);
+    const termMatches = queryTerms.reduce((total, term) => total + (tokenSet.has(normalizeTemporalTerm(term)) ? 1 : 0), 0);
+    const subjectMatches = countSubjectMatches(lowerContent, subjectTerms);
+    const eventGroupMatches = countMatchedEventGroups(lowerContent, conceptGroups);
+    const isPlanningLike = containsPlanningMarker(lowerContent);
+    const score = termMatches
+        + (subjectMatches * SUBJECT_MATCH_BONUS)
+        + (eventGroupMatches * EVENT_GROUP_MATCH_BONUS)
+        - (isPlanningLike ? PLANNING_PENALTY : 0);
+    if (score <= 0)
+        return null;
+    return {
+        dateKey: formatDateLabel(memory.created_at),
+        memory,
+        score,
+        subjectMatches,
+        eventGroupMatches,
+        isPlanningLike,
+    };
+}
+function compareGeneralTemporalCandidates(left, right) {
+    if (left.score !== right.score)
+        return right.score - left.score;
+    if (left.eventGroupMatches !== right.eventGroupMatches) {
+        return right.eventGroupMatches - left.eventGroupMatches;
+    }
+    if (left.subjectMatches !== right.subjectMatches) {
+        return right.subjectMatches - left.subjectMatches;
+    }
+    if (left.isPlanningLike !== right.isPlanningLike) {
+        return left.isPlanningLike ? 1 : -1;
+    }
+    return left.memory.created_at.getTime() - right.memory.created_at.getTime();
+}
+function buildNormalizedTokenSet(content) {
+    return new Set(content
+        .toLowerCase()
+        .replace(/\b([a-z]+)'s\b/g, '$1')
+        .replace(/[^a-z0-9'\s-]/g, ' ')
+        .split(/\s+/)
+        .filter((token) => token.length >= QUERY_TERM_MIN_LENGTH)
+        .map(normalizeTemporalTerm));
+}
+function normalizeTemporalTerm(term) {
+    const irregular = IRREGULAR_NORMALIZATION[term];
+    if (irregular)
+        return irregular;
+    for (const suffix of STEM_SUFFIXES) {
+        if (term.length > suffix.length + 2 && term.endsWith(suffix)) {
+            return term.slice(0, -suffix.length);
+        }
+    }
+    return term;
+}
+function buildGeneralDurationEndpointLines(candidates, query) {
+    if (!DURATION_QUERY.test(query.toLowerCase()))
+        return [];
+    const selected = selectDurationEndpoints(candidates);
+    if (selected.length < DURATION_ENDPOINT_LIMIT)
+        return [];
+    return [
+        formatEndpointLine('earliest matching event', selected[0]),
+        formatEndpointLine('latest matching event', selected[1]),
+        `- elapsed between endpoints: ${formatDuration(diffDays(selected[0].memory.created_at, selected[1].memory.created_at))}`,
+    ];
+}
+function selectDurationEndpoints(candidates) {
+    const stableCandidates = preferCompletedCandidates(candidates);
+    const byDate = new Map();
+    for (const candidate of stableCandidates) {
+        const existing = byDate.get(candidate.dateKey);
+        if (!existing || compareGeneralTemporalCandidates(candidate, existing) < 0) {
+            byDate.set(candidate.dateKey, candidate);
+        }
+    }
+    const distinct = [...byDate.values()].sort((left, right) => left.memory.created_at.getTime() - right.memory.created_at.getTime());
+    if (distinct.length < DURATION_ENDPOINT_LIMIT)
+        return [];
+    return [distinct[0], distinct[distinct.length - 1]];
+}
+function preferCompletedCandidates(candidates) {
+    const completed = candidates.filter((candidate) => !candidate.isPlanningLike);
+    return completed.length >= DURATION_ENDPOINT_LIMIT ? completed : candidates;
+}
+function countSubjectMatches(content, subjectTerms) {
+    return subjectTerms.reduce((total, subject) => total + (content.includes(subject) ? 1 : 0), 0);
+}
+function countMatchedEventGroups(content, conceptGroups) {
+    return conceptGroups.filter((group) => group.some((synonym) => content.includes(synonym))).length;
+}
+function containsPlanningMarker(content) {
+    return PLANNING_MARKERS.some((marker) => content.includes(marker));
+}
+function selectDistinctDateEndpoints(candidates) {
+    const byDate = new Map();
+    for (const candidate of candidates) {
+        const existing = byDate.get(candidate.dateKey);
+        if (!existing || candidate.score > existing.score)
+            byDate.set(candidate.dateKey, candidate);
+    }
+    return [...byDate.values()].sort((left, right) => left.memory.created_at.getTime() - right.memory.created_at.getTime()).slice(0, 2);
+}
+function formatEndpointLine(label, candidate) {
+    return `- ${label}: ${candidate.dateKey} — ${truncateEvidence(candidate.memory.content)}`;
+}
+function truncateEvidence(content) {
+    const normalized = content.replace(/\s+/g, ' ').trim();
+    if (normalized.length <= EVIDENCE_MAX_CHARS)
+        return normalized;
+    return `${normalized.slice(0, EVIDENCE_MAX_CHARS - 3)}...`;
+}
+function diffDays(first, second) {
+    return Math.round((second.getTime() - first.getTime()) / 86400000);
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Normalized content fingerprints for temporal retrieval protection.
+ * Different rows can duplicate the same event text, so protection needs
+ * to reason about content identity, not row identity.
+ */
+export declare function buildTemporalFingerprint(content: string): string;

package/dist/services/temporal-fingerprint.js

@@ -0,0 +1,12 @@
+/**
+ * Normalized content fingerprints for temporal retrieval protection.
+ * Different rows can duplicate the same event text, so protection needs
+ * to reason about content identity, not row identity.
+ */
+export function buildTemporalFingerprint(content) {
+    return content
+        .replace(/^As of [^,]+,?\s*/i, '')
+        .replace(/[^a-z0-9]+/gi, ' ')
+        .trim()
+        .toLowerCase();
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Shared temporal formatting helpers.
+ *
+ * Used by retrieval-format and temporal-endpoint-evidence to render the
+ * same date keys and duration strings without each file maintaining its
+ * own copy.
+ */
+export declare function formatDateLabel(date: Date): string;
+export declare function formatDuration(days: number): string;

package/dist/services/temporal-format.js

@@ -0,0 +1,21 @@
+/**
+ * Shared temporal formatting helpers.
+ *
+ * Used by retrieval-format and temporal-endpoint-evidence to render the
+ * same date keys and duration strings without each file maintaining its
+ * own copy.
+ */
+const DAYS_PER_WEEK = 7;
+const DAYS_PER_MONTH = 30;
+export function formatDateLabel(date) {
+    return date.toISOString().slice(0, 10);
+}
+export function formatDuration(days) {
+    if (days < DAYS_PER_WEEK)
+        return `${days} day${days !== 1 ? 's' : ''}`;
+    const weeks = Math.round(days / DAYS_PER_WEEK);
+    if (days < DAYS_PER_MONTH)
+        return `~${weeks} week${weeks !== 1 ? 's' : ''} (${days} days)`;
+    const months = Math.round(days / DAYS_PER_MONTH);
+    return `~${months} month${months !== 1 ? 's' : ''} (${days} days)`;
+}

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

@@ -0,0 +1,39 @@
+/**
+ * BEAM v38: read-time temporal intent classifier.
+ *
+ * Pure regex/keyword classification — no LLM call, no DB lookup.
+ * Used by `memory-search.ts` to decide whether to rerank candidates
+ * by `state_key` activity (CURRENT_STATE) or leave ordering alone.
+ *
+ * Scope: only CURRENT_STATE is "live" today — the other labels are
+ * recorded for observability but produce no rerank. Keeping the surface
+ * narrow avoids speculative knobs while leaving room to grow.
+ */
+/** Intent labels recognized at read time. */
+export declare enum TemporalIntent {
+    /**
+     * "What is X now?" / "Where do I live?" — answer should reflect the
+     * active state. Triggers the state_key rerank.
+     */
+    CURRENT_STATE = "current_state",
+    /**
+     * "What was X in March?" / "What was my salary last year?" — answer
+     * needs a snapshot at a past time. No rerank today; reserved.
+     */
+    HISTORICAL_AT_TIME = "historical_at_time",
+    /**
+     * "How long have I had X?" — duration question. No rerank today.
+     */
+    DURATION = "duration",
+    /** Everything else — no temporal intent inferred. */
+    NONE = "none"
+}
+/**
+ * Classify a query into a TemporalIntent. Order matters:
+ *   - HISTORICAL and DURATION are tested first because they may share
+ *     phrasing ("how long have I lived…" reads like duration even if
+ *     "current" appears in the question).
+ *   - CURRENT_STATE is the catch-all for active-state phrasings.
+ *   - Everything else returns NONE.
+ */
+export declare function classifyTemporalIntent(query: string): TemporalIntent;

package/dist/services/temporal-intent.js

@@ -0,0 +1,78 @@
+/**
+ * BEAM v38: read-time temporal intent classifier.
+ *
+ * Pure regex/keyword classification — no LLM call, no DB lookup.
+ * Used by `memory-search.ts` to decide whether to rerank candidates
+ * by `state_key` activity (CURRENT_STATE) or leave ordering alone.
+ *
+ * Scope: only CURRENT_STATE is "live" today — the other labels are
+ * recorded for observability but produce no rerank. Keeping the surface
+ * narrow avoids speculative knobs while leaving room to grow.
+ */
+/** Intent labels recognized at read time. */
+export var TemporalIntent;
+(function (TemporalIntent) {
+    /**
+     * "What is X now?" / "Where do I live?" — answer should reflect the
+     * active state. Triggers the state_key rerank.
+     */
+    TemporalIntent["CURRENT_STATE"] = "current_state";
+    /**
+     * "What was X in March?" / "What was my salary last year?" — answer
+     * needs a snapshot at a past time. No rerank today; reserved.
+     */
+    TemporalIntent["HISTORICAL_AT_TIME"] = "historical_at_time";
+    /**
+     * "How long have I had X?" — duration question. No rerank today.
+     */
+    TemporalIntent["DURATION"] = "duration";
+    /** Everything else — no temporal intent inferred. */
+    TemporalIntent["NONE"] = "none";
+})(TemporalIntent || (TemporalIntent = {}));
+const HISTORICAL_AT_TIME_PATTERNS = [
+    /\bwhat was (?:my|the|his|her|their)\b/,
+    /\bin (?:january|february|march|april|may|june|july|august|september|october|november|december)\b/,
+    /\b(?:last|previous) (?:year|month|week|quarter)\b/,
+    /\bback in\b/,
+    /\bduring (?:the\s+)?\d{4}\b/,
+    /\bas of\b/,
+    /\bbefore (?:switching|moving|changing|leaving)\b/,
+];
+const DURATION_PATTERNS = [
+    /\bhow long (?:have|has|did|do)\b/,
+    /\bfor how long\b/,
+    /\b(?:since|over) the (?:past|last)\b/,
+    /\bduration of\b/,
+];
+const CURRENT_STATE_PATTERNS = [
+    /\bcurrent(?:ly)?\b/,
+    /\b(?:right )?now\b/,
+    /\btoday\b/,
+    /\bat (?:the )?(?:moment|present)\b/,
+    /\bwhere do (?:i|you|we) live\b/,
+    /\bwhat(?:'|\s)?s? (?:my|your|his|her|their) current\b/,
+    /\bwhat (?:is|are) (?:my|your|his|her|their) (?:current|now)\b/,
+    /\bwhere (?:am|are) (?:i|you|we) (?:living|working|based)\b/,
+    /\b(?:as of|by) (?:today|now)\b/,
+];
+/**
+ * Classify a query into a TemporalIntent. Order matters:
+ *   - HISTORICAL and DURATION are tested first because they may share
+ *     phrasing ("how long have I lived…" reads like duration even if
+ *     "current" appears in the question).
+ *   - CURRENT_STATE is the catch-all for active-state phrasings.
+ *   - Everything else returns NONE.
+ */
+export function classifyTemporalIntent(query) {
+    const normalized = query.toLowerCase();
+    if (DURATION_PATTERNS.some((pattern) => pattern.test(normalized))) {
+        return TemporalIntent.DURATION;
+    }
+    if (HISTORICAL_AT_TIME_PATTERNS.some((pattern) => pattern.test(normalized))) {
+        return TemporalIntent.HISTORICAL_AT_TIME;
+    }
+    if (CURRENT_STATE_PATTERNS.some((pattern) => pattern.test(normalized))) {
+        return TemporalIntent.CURRENT_STATE;
+    }
+    return TemporalIntent.NONE;
+}

package/dist/services/temporal-query-constraints.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Query-time temporal constraint ranking for explicit month/date questions.
+ *
+ * This is intentionally narrow: it only reacts when the user states a month
+ * constraint in the query, then boosts/protects candidates whose content or
+ * observation timestamp matches that month. It complements temporal ordering
+ * expansion, which handles "before/after/when" phrasing.
+ */
+import type { SearchResult } from '../db/repository-types.js';
+export interface TemporalConstraintRankingResult {
+    constraints: string[];
+    protectedFingerprints: string[];
+    protectedIds: string[];
+    results: SearchResult[];
+}
+export declare function applyTemporalQueryConstraints(query: string, results: SearchResult[], boost: number): TemporalConstraintRankingResult;

package/dist/services/temporal-query-constraints.js

@@ -0,0 +1,107 @@
+/**
+ * Query-time temporal constraint ranking for explicit month/date questions.
+ *
+ * This is intentionally narrow: it only reacts when the user states a month
+ * constraint in the query, then boosts/protects candidates whose content or
+ * observation timestamp matches that month. It complements temporal ordering
+ * expansion, which handles "before/after/when" phrasing.
+ */
+import { buildTemporalFingerprint } from './temporal-fingerprint.js';
+import { countKeywordMatches } from './query-keyword-matches.js';
+const MONTHS = [
+    'january', 'february', 'march', 'april', 'may', 'june',
+    'july', 'august', 'september', 'october', 'november', 'december',
+];
+const QUERY_STOP_WORDS = new Set([
+    'what', 'when', 'where', 'which', 'who', 'whom', 'whose', 'why', 'how',
+    'did', 'does', 'do', 'was', 'were', 'is', 'are', 'the', 'a', 'an', 'and',
+    'or', 'to', 'of', 'in', 'for', 'on', 'with', 'about', 'user', 'their',
+    'they', 'them', 'there', 'happen', 'happened', 'event', 'events',
+]);
+const MAX_PROTECTED_TEMPORAL_CONSTRAINTS = 3;
+export function applyTemporalQueryConstraints(query, results, boost) {
+    const constraints = extractTemporalConstraints(query);
+    if (constraints.length === 0 || boost <= 0) {
+        return emptyResult(results);
+    }
+    const keywords = extractQueryKeywords(query);
+    const scored = results
+        .map((result) => scoreTemporalCandidate(result, constraints, keywords, boost))
+        .sort((left, right) => right.result.score - left.result.score);
+    const protectedCandidates = scored.filter((item) => item.matched).slice(0, MAX_PROTECTED_TEMPORAL_CONSTRAINTS);
+    return {
+        constraints: constraints.map(formatConstraint),
+        protectedFingerprints: protectedCandidates.map((item) => buildTemporalFingerprint(item.result.content)),
+        protectedIds: protectedCandidates.map((item) => item.result.id),
+        results: scored.map((item) => item.result),
+    };
+}
+function extractTemporalConstraints(query) {
+    const lower = query.toLowerCase();
+    const constraints = [];
+    for (let index = 0; index < MONTHS.length; index++) {
+        const monthName = MONTHS[index];
+        const pattern = new RegExp(`\\b${monthName}\\b(?:\\s+(\\d{4}))?`, 'i');
+        const match = lower.match(pattern);
+        if (!match)
+            continue;
+        const year = match[1] ? parseInt(match[1], 10) : undefined;
+        constraints.push({ monthIndex: index, monthName, year });
+    }
+    return constraints;
+}
+function scoreTemporalCandidate(result, constraints, keywords, boost) {
+    if (!matchesAnyConstraint(result, constraints) || !hasKeywordSupport(result.content, keywords)) {
+        return { result, matched: false };
+    }
+    const keywordBoost = countKeywordMatches(result.content, keywords) * 0.1;
+    return {
+        result: { ...result, score: result.score + boost + keywordBoost },
+        matched: true,
+    };
+}
+function matchesAnyConstraint(result, constraints) {
+    return constraints.some((constraint) => (contentMatchesConstraint(result.content, constraint)
+        || dateMatchesConstraint(result.created_at, constraint)
+        || dateMatchesConstraint(result.observed_at, constraint)));
+}
+function contentMatchesConstraint(content, constraint) {
+    const lower = content.toLowerCase();
+    if (!lower.includes(constraint.monthName))
+        return false;
+    if (constraint.year === undefined)
+        return true;
+    return lower.includes(String(constraint.year));
+}
+function dateMatchesConstraint(date, constraint) {
+    if (date.getUTCMonth() !== constraint.monthIndex)
+        return false;
+    if (constraint.year === undefined)
+        return true;
+    return date.getUTCFullYear() === constraint.year;
+}
+function hasKeywordSupport(content, keywords) {
+    if (keywords.length === 0)
+        return true;
+    const requiredMatches = Math.min(2, keywords.length);
+    return countKeywordMatches(content, keywords) >= requiredMatches;
+}
+function extractQueryKeywords(query) {
+    const words = query
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, ' ')
+        .split(/\s+/)
+        .filter((word) => word.length > 2)
+        .filter((word) => !QUERY_STOP_WORDS.has(word))
+        .filter((word) => !MONTHS.includes(word))
+        .filter((word) => !/^\d{4}$/.test(word));
+    return [...new Set(words)];
+}
+function formatConstraint(constraint) {
+    return constraint.year === undefined
+        ? constraint.monthName
+        : `${constraint.monthName} ${constraint.year}`;
+}
+function emptyResult(results) {
+    return { constraints: [], protectedFingerprints: [], protectedIds: [], results };
+}

package/dist/services/temporal-query-expansion.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Deterministic query expansion for temporal-order questions.
+ * Pulls exact keyword candidates and nearby session memories when the query
+ * asks about sequence, relative timing, or duration.
+ */
+import type { SearchResult } from '../db/repository-types.js';
+import type { SearchStore } from '../db/stores.js';
+export declare function isTemporalOrderingQuery(query: string): boolean;
+export declare function extractTemporalQueryKeywords(query: string): string[];
+export declare function expandTemporalQuery(repo: SearchStore, userId: string, query: string, queryEmbedding: number[], excludeIds: Set<string>, limit: number, referenceTime?: Date): Promise<{
+    memories: SearchResult[];
+    keywords: string[];
+    anchorIds: string[];
+}>;