@atomicmemory/core 1.0.0

package/dist/services/lesson-service.js

@@ -0,0 +1,178 @@
+/**
+ * Lesson detection and pre-retrieval defense service.
+ *
+ * Implements A-MemGuard's self-reinforcing defense:
+ *   1. Detect failure patterns during ingest (sanitizer blocks, trust violations,
+ *      high-confidence contradictions) and store as lessons.
+ *   2. Before retrieval, check query against known lessons to warn or block.
+ *
+ * Phase 6 security layer — builds on Phase 3 trust scoring and sanitization.
+ */
+import { embedText } from './embedding.js';
+import { emitAuditEvent } from './audit-events.js';
+import { config } from '../config.js';
+const LESSON_SIMILARITY_THRESHOLD = 0.75;
+const LESSON_CHECK_LIMIT = 3;
+/**
+ * Check a query against known lessons before returning retrieval results.
+ * Returns warnings for medium/high severity, blocks on critical.
+ */
+export async function checkLessons(repo, userId, query) {
+    const embedding = await embedText(query);
+    const matches = await repo.findSimilarLessons(userId, embedding, LESSON_SIMILARITY_THRESHOLD, LESSON_CHECK_LIMIT);
+    if (matches.length === 0) {
+        return { safe: true, matchedLessons: [], warnings: [], highestSeverity: 'none' };
+    }
+    const warnings = matches.map((m) => formatLessonWarning(m));
+    const highestSeverity = resolveHighestSeverity(matches.map((m) => m.lesson.severity));
+    const safe = highestSeverity !== 'critical';
+    if (config.auditLoggingEnabled) {
+        emitAuditEvent('lesson:match', userId, {
+            query: query.slice(0, 200),
+            matchCount: matches.length,
+            highestSeverity,
+            safe,
+        });
+    }
+    return { safe, matchedLessons: matches, warnings, highestSeverity };
+}
+/**
+ * Detect and store a lesson from a sanitization block.
+ * Called when input sanitizer catches an injection attempt.
+ */
+export async function recordInjectionLesson(repo, ctx) {
+    if (!ctx.sanitizationResult || ctx.sanitizationResult.passed)
+        return null;
+    const blockFindings = ctx.sanitizationResult.findings.filter((f) => f.severity === 'block');
+    if (blockFindings.length === 0)
+        return null;
+    const pattern = buildInjectionPattern(ctx.content, blockFindings);
+    const embedding = await embedText(pattern);
+    const severity = blockFindings.length >= 3 ? 'critical' : 'high';
+    const lessonId = await repo.createLesson({
+        userId: ctx.userId,
+        lessonType: 'injection_blocked',
+        pattern,
+        embedding,
+        severity,
+        metadata: {
+            sourceSite: ctx.sourceSite,
+            findingCount: blockFindings.length,
+            rules: blockFindings.map((f) => f.rule),
+        },
+    });
+    emitLessonAuditEvent(ctx.userId, 'injection_blocked', lessonId, severity);
+    return lessonId;
+}
+/**
+ * Detect and store a lesson from a trust score violation.
+ * Called when a fact is rejected for being below the trust threshold.
+ */
+export async function recordTrustViolationLesson(repo, ctx) {
+    if (ctx.trustScore === undefined || ctx.trustScore >= config.trustScoreMinThreshold)
+        return null;
+    const pattern = `Low-trust content from ${ctx.sourceSite}: "${ctx.content.slice(0, 200)}"`;
+    const embedding = await embedText(pattern);
+    const lessonId = await repo.createLesson({
+        userId: ctx.userId,
+        lessonType: 'trust_violation',
+        pattern,
+        embedding,
+        severity: ctx.trustScore < 0.1 ? 'high' : 'medium',
+        metadata: {
+            sourceSite: ctx.sourceSite,
+            trustScore: ctx.trustScore,
+            threshold: config.trustScoreMinThreshold,
+        },
+    });
+    emitLessonAuditEvent(ctx.userId, 'trust_violation', lessonId, 'medium');
+    return lessonId;
+}
+/**
+ * Detect and store a lesson from a high-confidence contradiction.
+ * Called when SUPERSEDE or DELETE fires with high contradiction confidence.
+ */
+export async function recordContradictionLesson(repo, ctx) {
+    if (!ctx.contradictionConfidence || ctx.contradictionConfidence < 0.8)
+        return null;
+    const pattern = `High-confidence contradiction (${ctx.contradictionConfidence.toFixed(2)}): "${ctx.content.slice(0, 200)}"`;
+    const embedding = await embedText(pattern);
+    const lessonId = await repo.createLesson({
+        userId: ctx.userId,
+        lessonType: 'contradiction_pattern',
+        pattern,
+        embedding,
+        sourceMemoryIds: ctx.supersededMemoryId ? [ctx.supersededMemoryId] : [],
+        severity: 'medium',
+        metadata: {
+            contradictionConfidence: ctx.contradictionConfidence,
+            supersededMemoryId: ctx.supersededMemoryId,
+        },
+    });
+    emitLessonAuditEvent(ctx.userId, 'contradiction_pattern', lessonId, 'medium');
+    return lessonId;
+}
+/**
+ * Record a user-reported lesson (explicit feedback that a memory was wrong).
+ */
+export async function recordUserReportedLesson(repo, userId, pattern, sourceMemoryIds, severity = 'high') {
+    const embedding = await embedText(pattern);
+    const lessonId = await repo.createLesson({
+        userId,
+        lessonType: 'user_reported',
+        pattern,
+        embedding,
+        sourceMemoryIds,
+        severity,
+    });
+    emitLessonAuditEvent(userId, 'user_reported', lessonId, severity);
+    return lessonId;
+}
+/** Get all active lessons for a user. */
+export async function getUserLessons(repo, userId) {
+    return repo.getLessonsByUser(userId);
+}
+/** Get lesson stats for a user. */
+export async function getLessonStats(repo, userId) {
+    const lessons = await repo.getLessonsByUser(userId);
+    const byType = {};
+    for (const lesson of lessons) {
+        byType[lesson.lesson_type] = (byType[lesson.lesson_type] ?? 0) + 1;
+    }
+    return { totalActive: lessons.length, byType };
+}
+function formatLessonWarning(match) {
+    return `[${match.lesson.severity}] ${match.lesson.lesson_type}: ${match.lesson.pattern.slice(0, 100)} (similarity: ${match.similarity.toFixed(2)})`;
+}
+function resolveHighestSeverity(severities) {
+    const order = ['low', 'medium', 'high', 'critical'];
+    let highest = 0;
+    for (const s of severities) {
+        const idx = order.indexOf(s);
+        if (idx > highest)
+            highest = idx;
+    }
+    return order[highest];
+}
+function buildInjectionPattern(content, findings) {
+    const rules = findings.map((f) => f.rule).join(', ');
+    return `Injection attempt blocked (${rules}): "${content.slice(0, 200)}"`;
+}
+function emitLessonAuditEvent(userId, lessonType, lessonId, severity) {
+    if (!config.auditLoggingEnabled)
+        return;
+    emitAuditEvent('lesson:created', userId, { lessonType, severity }, { lessonId });
+}
+/**
+ * Record lessons for memories removed by consensus validation.
+ * Creates a `consensus_violation` lesson for each divergent memory.
+ */
+export async function recordConsensusLessons(lessons, userId, result, memories) {
+    for (const judgment of result.judgments) {
+        if (judgment.aligned)
+            continue;
+        const memory = memories.find((m) => m.id === judgment.memoryId);
+        const pattern = `Consensus violation: "${memory?.content.slice(0, 150) ?? judgment.memoryId}" — ${judgment.divergenceReason}`;
+        await recordUserReportedLesson(lessons, userId, pattern, [judgment.memoryId], 'medium');
+    }
+}

package/dist/services/literal-extractor.d.ts

@@ -0,0 +1,16 @@
+import type { EntityValuesRepository } from '../db/entity-values-repository.js';
+export interface LiteralExtractorDeps {
+    values: EntityValuesRepository;
+    model: string;
+}
+export interface ExtractInput {
+    userId: string;
+    factId: string;
+    factText: string;
+    observedAt: Date;
+}
+/**
+ * Extract literal (entity, attribute, value) triples from a single fact text
+ * and persist them to entity_values. Returns the count of triples inserted.
+ */
+export declare function extractLiteralsFromFact(deps: LiteralExtractorDeps, input: ExtractInput): Promise<number>;

package/dist/services/literal-extractor.js

@@ -0,0 +1,74 @@
+/**
+ * Ingest-side literal-value extractor.
+ *
+ * For each new fact, calls Haiku with tool-use to extract zero or more
+ * (entity, attribute, value, value_type) triples. Persists them to the
+ * entity_values table.
+ *
+ * The extractor errs on the side of NOT extracting — only literals that
+ * clearly map to "what is the X" / "when does X" / "how many X" question
+ * shapes are persisted. Narrative facts without a clean entity/attribute
+ * structure are skipped.
+ */
+import { callAnthropicTool } from './llm.js';
+const EXTRACT_TOOL_SCHEMA = {
+    name: 'extract_literal_triples',
+    description: 'Extract structured (entity, attribute, value) triples from a fact, if any.',
+    input_schema: {
+        type: 'object',
+        properties: {
+            triples: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    required: ['entity', 'attribute', 'value', 'value_type'],
+                    properties: {
+                        entity: { type: 'string', description: 'The subject. e.g. "first sprint", "API key", "test coverage"' },
+                        attribute: { type: 'string', description: 'The relation. e.g. "end date", "daily quota", "percentage"' },
+                        value: { type: 'string', description: 'LITERAL value AS IT APPEARS in the fact. Do not paraphrase.' },
+                        value_type: {
+                            type: 'string',
+                            enum: ['date', 'number', 'string', 'duration', 'list'],
+                        },
+                    },
+                },
+            },
+        },
+        required: ['triples'],
+    },
+};
+const EXTRACTOR_SYSTEM = `You are extracting (entity, attribute, value) triples from a single user fact.
+
+Output triples ONLY when the fact contains a clean structured claim like:
+- "first sprint ends March 29" → (first sprint, end date, March 29, date)
+- "API key has 1,200 daily calls" → (API key, daily quota, 1,200 calls per day, number)
+- "test coverage is 78%" → (test coverage, percentage, 78%, number)
+- "uses vanilla JavaScript ES2021" → (project, technology, vanilla JavaScript ES2021, string)
+
+Skip facts that are narrative ("the user decided to..."), opinions, or vague.
+
+CRITICAL: the value field must be the LITERAL string from the fact. Do not paraphrase. "1,200 calls per day" not "around 1000 calls". "March 29" not "end of March". "78%" not "high coverage".
+
+Call extract_literal_triples. If no triples, return an empty array.`;
+/**
+ * Extract literal (entity, attribute, value) triples from a single fact text
+ * and persist them to entity_values. Returns the count of triples inserted.
+ */
+export async function extractLiteralsFromFact(deps, input) {
+    if (!input.factText.trim())
+        return 0;
+    const result = await callAnthropicTool(deps.model, EXTRACTOR_SYSTEM, `Fact: ${input.factText}`, EXTRACT_TOOL_SCHEMA);
+    if (result.triples.length === 0)
+        return 0;
+    const rows = result.triples.map(t => ({
+        userId: input.userId,
+        entity: t.entity,
+        attribute: t.attribute,
+        value: t.value,
+        valueType: t.value_type,
+        observedAt: input.observedAt,
+        factId: input.factId,
+    }));
+    await deps.values.insertMany(rows);
+    return rows.length;
+}

package/dist/services/literal-list-protection.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Protect literal list-answer candidates from late-stage diversity selection.
+ *
+ * LoCoMo-style questions such as "What are Melanie's pets' names?" and
+ * "What musical artists has Melanie seen?" often need short memories that
+ * contain the exact named answer. These memories can be less semantically broad
+ * than neighboring context, so MMR may drop them unless we mark high-signal
+ * candidates as protected before final selection.
+ */
+import type { SearchResult } from '../db/repository-types.js';
+export interface LiteralListProtectionResult {
+    protectedFingerprints: string[];
+    protectedIds: string[];
+    reasons: string[];
+    results: SearchResult[];
+}
+export declare function protectLiteralListAnswerCandidates(query: string, candidates: SearchResult[], maxProtected: number): LiteralListProtectionResult;

package/dist/services/literal-list-protection.js

@@ -0,0 +1,134 @@
+/**
+ * Protect literal list-answer candidates from late-stage diversity selection.
+ *
+ * LoCoMo-style questions such as "What are Melanie's pets' names?" and
+ * "What musical artists has Melanie seen?" often need short memories that
+ * contain the exact named answer. These memories can be less semantically broad
+ * than neighboring context, so MMR may drop them unless we mark high-signal
+ * candidates as protected before final selection.
+ */
+import { buildTemporalFingerprint } from './temporal-fingerprint.js';
+import { isLiteralDetailQuery } from './literal-query-expansion.js';
+const MIN_SIGNAL_SCORE = 3;
+const PROTECTED_SCORE_BONUS = 4;
+const PET_TERMS = ['pet', 'pets', 'cat', 'cats', 'dog', 'dogs'];
+const MUSIC_TERMS = ['artist', 'artists', 'band', 'bands', 'music', 'musical', 'concert', 'song', 'songs'];
+const BOOK_TERMS = ['book', 'books', 'title', 'read', 'reading'];
+const NAME_TERMS = ['name', 'names', 'called', 'named'];
+const SEEN_EVENT_TERMS = ['seen', 'saw', 'attended', 'concert', 'show'];
+const PERFORMANCE_TERMS = ['played', 'playing', 'dancing', 'singing', 'live', 'stage', 'show', 'concert'];
+const ATTENDANCE_TERMS = ['attended', 'saw', 'seen', 'concert', 'show'];
+export function protectLiteralListAnswerCandidates(query, candidates, maxProtected) {
+    if (maxProtected <= 0 || !isLiteralDetailQuery(query)) {
+        return emptyProtection(candidates);
+    }
+    const intent = classifyListIntent(query);
+    if (!intent.hasListIntent) {
+        return emptyProtection(candidates);
+    }
+    const protectedCandidates = candidates
+        .map((candidate) => scoreCandidate(candidate, intent))
+        .filter((candidate) => candidate.score >= MIN_SIGNAL_SCORE)
+        .sort((left, right) => right.score - left.score)
+        .slice(0, maxProtected);
+    return {
+        protectedFingerprints: protectedCandidates.map((item) => buildTemporalFingerprint(item.result.content)),
+        protectedIds: protectedCandidates.map((item) => item.result.id),
+        reasons: [...new Set(protectedCandidates.flatMap((item) => item.reasons))],
+        results: boostProtectedCandidates(candidates, protectedCandidates),
+    };
+}
+function classifyListIntent(query) {
+    const lower = query.toLowerCase();
+    return {
+        hasListIntent: containsAny(lower, NAME_TERMS) || containsAny(lower, PET_TERMS)
+            || containsAny(lower, MUSIC_TERMS) || containsAny(lower, BOOK_TERMS),
+        wantsNames: containsAny(lower, NAME_TERMS),
+        wantsPets: containsAny(lower, PET_TERMS),
+        wantsMusic: containsAny(lower, MUSIC_TERMS),
+        wantsBooks: containsAny(lower, BOOK_TERMS),
+        wantsSeenEvent: containsAny(lower, SEEN_EVENT_TERMS),
+    };
+}
+function scoreCandidate(result, intent) {
+    const content = result.content;
+    const lower = content.toLowerCase();
+    const hasQuoted = hasQuotedTitle(content);
+    const hasLeadingQuote = hasLeadingQuotedTitle(content);
+    const hasAttendance = containsAny(lower, ATTENDANCE_TERMS);
+    const reasons = [];
+    const score = scoreNamedEntity(content, intent, reasons)
+        + scoreQuotedOrAttendance(intent, hasQuoted, hasLeadingQuote, hasAttendance, reasons)
+        + scoreDomainTerms(lower, intent, reasons)
+        + scorePerformanceEvent(lower, intent, hasLeadingQuote, reasons);
+    return { result, score, reasons };
+}
+function scoreNamedEntity(content, intent, reasons) {
+    if (!(intent.wantsPets || intent.wantsNames))
+        return 0;
+    if (!/\bnamed\s+[A-Z][A-Za-z'-]+/.test(content))
+        return 0;
+    reasons.push('named-entity');
+    return 3;
+}
+function scoreQuotedOrAttendance(intent, hasQuoted, hasLeadingQuote, hasAttendance, reasons) {
+    const seenEventScore = scoreSeenMusicEvent(intent, hasLeadingQuote, hasAttendance, reasons);
+    if (seenEventScore > 0)
+        return seenEventScore;
+    if ((intent.wantsMusic || intent.wantsBooks) && hasQuoted) {
+        reasons.push('quoted-title');
+        return 3;
+    }
+    return 0;
+}
+function scoreSeenMusicEvent(intent, hasLeadingQuote, hasAttendance, reasons) {
+    if (!intent.wantsMusic || !intent.wantsSeenEvent)
+        return 0;
+    if (hasLeadingQuote) {
+        reasons.push('quoted-title');
+        return 4;
+    }
+    if (!hasAttendance)
+        return 0;
+    reasons.push('attendance-event');
+    return 3;
+}
+function scoreDomainTerms(lower, intent, reasons) {
+    let score = 0;
+    score += addSignal(intent.wantsPets && containsAny(lower, PET_TERMS), reasons, 'pet-domain', 1.5);
+    score += addSignal(intent.wantsMusic && containsAny(lower, MUSIC_TERMS), reasons, 'music-domain', 1.5);
+    score += addSignal(intent.wantsBooks && containsAny(lower, BOOK_TERMS), reasons, 'book-domain', 1.5);
+    return score;
+}
+function scorePerformanceEvent(lower, intent, hasLeadingQuote, reasons) {
+    const hasPerformanceSignal = intent.wantsMusic && intent.wantsSeenEvent
+        && hasLeadingQuote && containsAny(lower, PERFORMANCE_TERMS);
+    return addSignal(hasPerformanceSignal, reasons, 'performance-event', 2.5);
+}
+function addSignal(enabled, reasons, reason, score) {
+    if (!enabled)
+        return 0;
+    reasons.push(reason);
+    return score;
+}
+function hasQuotedTitle(content) {
+    return /["'“‘][A-Z][^"'”’]{2,}["'”’]/.test(content);
+}
+function hasLeadingQuotedTitle(content) {
+    return /^\s*["'“‘][A-Z][^"'”’]{2,}["'”’]/.test(content);
+}
+function containsAny(content, terms) {
+    return terms.some((term) => new RegExp(`\\b${term}\\b`).test(content));
+}
+function boostProtectedCandidates(candidates, protectedCandidates) {
+    const protectedIds = new Set(protectedCandidates.map((item) => item.result.id));
+    return candidates.map((candidate) => {
+        if (!protectedIds.has(candidate.id)) {
+            return candidate;
+        }
+        return { ...candidate, score: candidate.score + PROTECTED_SCORE_BONUS };
+    });
+}
+function emptyProtection(results) {
+    return { protectedFingerprints: [], protectedIds: [], reasons: [], results };
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Deterministic retrieval helpers for literal autobiographical lookups.
+ *
+ * These queries ask for exact titles, quotes, object details, pets, photos,
+ * posters, store details, or other concrete memory fragments. Pure semantic
+ * retrieval often under-ranks those rows because the query phrasing is broad
+ * while the target memory contains a short literal detail.
+ *
+ * This module extracts high-signal lexical anchors from the query, finds exact
+ * keyword candidates, and boosts them enough to survive later reranking.
+ */
+import type { SearchResult } from '../db/repository-types.js';
+import type { SearchStore } from '../db/stores.js';
+export interface LiteralQueryExpansionResult {
+    memories: SearchResult[];
+    keywords: string[];
+}
+export declare function isLiteralDetailQuery(query: string): boolean;
+export declare function extractLiteralQueryKeywords(query: string): string[];
+export declare function expandLiteralQuery(repo: SearchStore, userId: string, query: string, queryEmbedding: number[], excludeIds: Set<string>, limit: number): Promise<LiteralQueryExpansionResult>;

package/dist/services/literal-query-expansion.js

@@ -0,0 +1,181 @@
+/**
+ * Deterministic retrieval helpers for literal autobiographical lookups.
+ *
+ * These queries ask for exact titles, quotes, object details, pets, photos,
+ * posters, store details, or other concrete memory fragments. Pure semantic
+ * retrieval often under-ranks those rows because the query phrasing is broad
+ * while the target memory contains a short literal detail.
+ *
+ * This module extracts high-signal lexical anchors from the query, finds exact
+ * keyword candidates, and boosts them enough to survive later reranking.
+ */
+import { fetchAndBoostKeywordCandidates } from './keyword-expansion.js';
+const DIRECT_LOOKUP_PREFIX = /^\s*(?:what|which|who|where|when)\b/i;
+const ABSTRACT_BLOCKERS = [
+    'attitude',
+    'important',
+    'inspired',
+    'meaning',
+    'motivated',
+    'reaction',
+    'realize',
+    'reason',
+    'represent',
+    'symbol',
+    'take away',
+    'why',
+];
+const LITERAL_SIGNALS = [
+    'book',
+    'books',
+    'bowl',
+    'cat',
+    'cats',
+    'clothing store',
+    'concert',
+    'decor',
+    'dog',
+    'dogs',
+    'drawing',
+    'fan',
+    'festival',
+    'flooring',
+    'furniture',
+    'grand canyon',
+    'guinea pig',
+    'library',
+    'meteor shower',
+    'music',
+    'musician',
+    'musicians',
+    'painting',
+    'paintings',
+    'pet',
+    'pets',
+    'photo',
+    'photos',
+    'poetry reading',
+    'poster',
+    'posters',
+    'pottery',
+    'road trip',
+    'shoe',
+    'shoes',
+    'sidewalk',
+    'sign',
+    'slipper',
+    'song',
+    'songs',
+    'store',
+    'title',
+    'workshop',
+];
+const SIGNAL_WINDOW_RADIUS = 2;
+const MAX_KEYWORDS = 8;
+const LITERAL_SCORE_BOOST = 0.75;
+const WORD_BOUNDARY = /\b[\w'’.-]+\b/g;
+const QUOTED_LITERAL = /["“”']([^"“”']{2,80})["“”']/g;
+const YEAR_PATTERN = /\b(?:19|20)\d{2}\b/g;
+const DATE_PATTERN = /\b\d{1,2}\s+(?:January|February|March|April|May|June|July|August|September|October|November|December)\b/gi;
+const MULTI_WORD_PROPER_NOUN = /\b[A-Z][A-Za-z'’.-]+(?:\s+[A-Z][A-Za-z'’.-]+)+\b/g;
+const STOP_WORDS = new Set([
+    'a', 'an', 'at', 'did', 'do', 'does', 'for', 'from', 'her', 'his', 'in',
+    'is', 'kind', 'of', 'on', 'say', 'the', 'their', 'type', 'was', 'were',
+    'what', 'when', 'where', 'which', 'who',
+]);
+export function isLiteralDetailQuery(query) {
+    const normalized = query.trim().toLowerCase();
+    if (!normalized || !DIRECT_LOOKUP_PREFIX.test(normalized))
+        return false;
+    if (ABSTRACT_BLOCKERS.some((signal) => normalized.includes(signal)))
+        return false;
+    return extractLiteralQueryKeywords(query).length > 0;
+}
+export function extractLiteralQueryKeywords(query) {
+    const candidates = new Set();
+    const normalized = query.trim();
+    if (!normalized)
+        return [];
+    addMatches(candidates, extractQuotedLiterals(normalized));
+    addMatches(candidates, extractNamedLiteralCandidates(normalized));
+    addMatches(candidates, extractTemporalAnchors(normalized));
+    addMatches(candidates, extractSignalWindows(normalized));
+    return [...candidates]
+        .map(cleanKeyword)
+        .filter((keyword) => keyword.length >= 2)
+        .slice(0, MAX_KEYWORDS);
+}
+export async function expandLiteralQuery(repo, userId, query, queryEmbedding, excludeIds, limit) {
+    const keywords = extractLiteralQueryKeywords(query);
+    if (keywords.length === 0)
+        return { memories: [], keywords: [] };
+    const boosted = await fetchAndBoostKeywordCandidates(repo, userId, keywords, queryEmbedding, excludeIds, limit, LITERAL_SCORE_BOOST);
+    return { memories: boosted, keywords };
+}
+function extractQuotedLiterals(query) {
+    const matches = [];
+    let match;
+    while ((match = QUOTED_LITERAL.exec(query)) !== null) {
+        matches.push(match[1]);
+    }
+    return matches;
+}
+function extractNamedLiteralCandidates(query) {
+    const candidates = new Set();
+    const multiWord = query.match(MULTI_WORD_PROPER_NOUN) ?? [];
+    for (const phrase of multiWord) {
+        candidates.add(phrase.trim());
+    }
+    const words = query.match(WORD_BOUNDARY) ?? [];
+    for (let i = 1; i < words.length; i++) {
+        const word = words[i];
+        if (/^[A-Z][A-Za-z'’.-]+$/.test(word) && !STOP_WORDS.has(word.toLowerCase())) {
+            candidates.add(word);
+        }
+    }
+    return [...candidates];
+}
+function extractTemporalAnchors(query) {
+    return [
+        ...(query.match(DATE_PATTERN) ?? []),
+        ...(query.match(YEAR_PATTERN) ?? []),
+    ];
+}
+function extractSignalWindows(query) {
+    const lowerWords = (query.toLowerCase().match(WORD_BOUNDARY) ?? []);
+    const originalWords = (query.match(WORD_BOUNDARY) ?? []);
+    const windows = new Set();
+    for (let i = 0; i < lowerWords.length; i++) {
+        const signalLength = matchedSignalLength(lowerWords, i);
+        if (signalLength === 0)
+            continue;
+        const start = Math.max(0, i - SIGNAL_WINDOW_RADIUS);
+        const end = Math.min(originalWords.length, i + signalLength + SIGNAL_WINDOW_RADIUS);
+        const window = originalWords.slice(start, end).join(' ');
+        windows.add(window);
+        windows.add(originalWords.slice(i, i + signalLength).join(' '));
+    }
+    return [...windows];
+}
+function matchedSignalLength(words, start) {
+    for (const signal of LITERAL_SIGNALS) {
+        const signalWords = signal.split(' ');
+        const candidate = words.slice(start, start + signalWords.length);
+        if (candidate.join(' ') === signal) {
+            return signalWords.length;
+        }
+    }
+    return 0;
+}
+function addMatches(target, values) {
+    for (const value of values)
+        target.add(value);
+}
+function cleanKeyword(keyword) {
+    return keyword
+        .trim()
+        .replace(/^[^\w"“”']+|[^\w"“”']+$/g, '')
+        .split(/\s+/)
+        .filter((word) => !STOP_WORDS.has(word.toLowerCase()))
+        .join(' ');
+}

package/dist/services/llm.d.ts

@@ -0,0 +1,61 @@
+/**
+ * LLM provider abstraction for chat completions.
+ * Supports OpenAI, Ollama, and any OpenAI-compatible API (LM Studio, etc).
+ * Provider is selected via PROVIDER_LLM env var.
+ */
+import { type WriteCostEventConfig } from './cost-telemetry.js';
+import type { LLMProviderName } from '../config.js';
+/**
+ * Config subset consumed by the LLM module. Same module-local-state
+ * pattern as embedding.ts: provider/model selection is startup-only
+ * (Phase 7 Step 3c), so holding the config as module state after init
+ * matches the effective contract.
+ */
+export interface LLMConfig extends WriteCostEventConfig {
+    llmProvider: LLMProviderName;
+    llmModel: string;
+    llmApiUrl?: string;
+    llmApiKey?: string;
+    openaiApiKey: string;
+    groqApiKey?: string;
+    anthropicApiKey?: string;
+    googleApiKey?: string;
+    ollamaBaseUrl: string;
+    llmSeed?: number;
+}
+/** Bind the LLM module's config. Called once by the composition root. */
+export declare function initLlm(config: LLMConfig): void;
+export interface ChatMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+export interface ChatOptions {
+    temperature?: number;
+    maxTokens?: number;
+    jsonMode?: boolean;
+    seed?: number;
+}
+export interface LLMProvider {
+    chat(messages: ChatMessage[], options?: ChatOptions): Promise<string>;
+}
+/** Create LLM provider from config. */
+export declare function createLLMProvider(): LLMProvider;
+/** Singleton-like LLM accessor that refreshes when runtime config changes. */
+export declare const llm: LLMProvider;
+/** Schema shape expected by callAnthropicTool. */
+export interface AnthropicToolSchema {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}
+/**
+ * Invoke an Anthropic model in forced tool-use mode and return the parsed
+ * tool input. Uses the module-local config (set by initLlm) for the API key.
+ *
+ * @param model   - Anthropic model ID (e.g. 'claude-sonnet-4-5').
+ * @param system  - System prompt.
+ * @param user    - User message.
+ * @param toolSchema - Tool definition; the model is forced to call this tool.
+ * @returns Parsed tool input cast to T.
+ */
+export declare function callAnthropicTool<T>(model: string, system: string, user: string, toolSchema: AnthropicToolSchema): Promise<T>;