@atomicmemory/core 1.0.0

package/dist/services/ingest-post-write.js

@@ -0,0 +1,117 @@
+/**
+ * Post-write processors for the ingest pipeline.
+ *
+ * Runs after the per-fact loop completes: backdates memories to a session
+ * timestamp, generates inter-memory links, and clusters related facts
+ * into composite memories. Each processor is independently skippable via
+ * the batch context.
+ *
+ * Composite generation is full-ingest-only. The caller controls this via
+ * the `compositesEnabled` field — only `performIngest` sets it to true.
+ */
+import { generateLinks } from './search-pipeline.js';
+import { buildComposites } from './composite-grouping.js';
+import { inferNamespace, deriveMajorityNamespace } from './namespace-retrieval.js';
+import { timed } from './timing.js';
+import { extractTopicAbstraction, TopicAbstractionError } from './topic-abstraction.js';
+import { embedText } from './embedding.js';
+import { updateMemoryTopicAbstraction } from '../db/repository-write.js';
+import { maybeBuildRecapsForUser } from './recap-builder.js';
+/**
+ * Run all post-write processors for a completed ingest batch.
+ * Order: backdate → links → composites (if caller-enabled).
+ */
+export async function runPostWriteProcessors(deps, userId, ctx) {
+    if (ctx.sessionTimestamp && ctx.memoryIds.length > 0) {
+        await timed(`${ctx.timingPrefix}.backdate`, () => deps.stores.memory.backdateMemories(ctx.memoryIds, ctx.sessionTimestamp));
+    }
+    const linksCreated = await timed(`${ctx.timingPrefix}.links`, () => generateLinks({ search: deps.stores.search, link: deps.stores.link, memory: deps.stores.memory, entity: deps.stores.entity, summaries: deps.stores.summaries, pool: deps.stores.pool }, userId, ctx.memoryIds, ctx.embeddingCache, deps.config));
+    let compositesCreated = 0;
+    if (ctx.compositesEnabled && ctx.storedFacts.length >= deps.config.compositeMinClusterSize) {
+        compositesCreated = await timed(`${ctx.timingPrefix}.composites`, () => generateAndStoreComposites(deps, userId, ctx.storedFacts, ctx.embeddingCache, ctx.sourceSite, ctx.sourceUrl, ctx.episodeId, ctx.sessionTimestamp));
+    }
+    let topicAbstractionApplied = false;
+    if (deps.config.topicAbstractionEnabled && ctx.memoryIds.length > 0 && ctx.chunkText) {
+        topicAbstractionApplied = await timed(`${ctx.timingPrefix}.topic-abstraction`, () => generateAndStoreTopicAbstraction(deps, userId, ctx.chunkText, ctx.memoryIds));
+    }
+    // Recap layer trigger: fire-and-forget background pass. Latency is only
+    // measured on ingest if the cluster threshold is met AND the synthesis
+    // happens to land synchronously; we deliberately don't await here so the
+    // ingest response isn't gated on episode-style consolidation.
+    if (deps.config.recapLayerEnabled && ctx.memoryIds.length > 0) {
+        void maybeBuildRecapsForUser(deps, userId).catch((err) => {
+            console.warn(`[recap] background trigger failed for user=${userId}: ${err.message}`);
+        });
+    }
+    return { linksCreated, compositesCreated, topicAbstractionApplied };
+}
+/**
+ * Extract a conceptual topic from the chunk, embed it, and tag every memory
+ * stored from this chunk with the topic + embedding. One LLM call per chunk.
+ *
+ * Fail-soft: if topic extraction or embedding throws, the post-write step is
+ * skipped (logged) and other processors continue. The memories themselves are
+ * already stored — topic_abstraction defaults to '' and topic_embedding to
+ * NULL on those rows, which excludes them from the topic-search RRF arm
+ * without breaking other retrieval paths.
+ */
+async function generateAndStoreTopicAbstraction(deps, userId, chunkText, memoryIds) {
+    try {
+        const { topic } = await extractTopicAbstraction(chunkText, '');
+        const embedding = await embedText(topic, 'document');
+        await updateMemoryTopicAbstraction(deps.stores.pool, userId, memoryIds, topic, embedding);
+        return true;
+    }
+    catch (err) {
+        if (err instanceof TopicAbstractionError) {
+            console.warn(`[topic-abstraction] skipped for ${memoryIds.length} memories: ${err.message}`);
+            return false;
+        }
+        throw err;
+    }
+}
+/** Generate composite memories by clustering related facts from a single episode. */
+async function generateAndStoreComposites(deps, userId, storedFacts, embeddingCache, sourceSite, sourceUrl, episodeId, sessionTimestamp) {
+    const memberNamespaceMap = new Map();
+    const compositeInputs = storedFacts
+        .filter((sf) => embeddingCache.has(sf.memoryId))
+        .map((sf) => {
+        const ns = inferNamespace(sf.fact.fact, sourceSite, sf.fact.keywords);
+        memberNamespaceMap.set(sf.memoryId, ns);
+        return {
+            memoryId: sf.memoryId,
+            content: sf.fact.fact,
+            embedding: embeddingCache.get(sf.memoryId),
+            importance: sf.fact.importance,
+            keywords: sf.fact.keywords,
+            headline: sf.fact.headline,
+        };
+    });
+    const composites = buildComposites(compositeInputs);
+    if (composites.length === 0)
+        return 0;
+    for (const composite of composites) {
+        const memberNamespaces = composite.memberMemoryIds.map((id) => memberNamespaceMap.get(id) ?? null);
+        const namespace = deriveMajorityNamespace(memberNamespaces);
+        await deps.stores.memory.storeMemory({
+            userId,
+            content: composite.content,
+            embedding: composite.embedding,
+            memoryType: 'composite',
+            importance: composite.importance,
+            sourceSite, sourceUrl, episodeId,
+            keywords: composite.keywords.join(' '),
+            summary: composite.headline,
+            overview: composite.overview,
+            trustScore: 1.0,
+            createdAt: sessionTimestamp,
+            observedAt: sessionTimestamp,
+            namespace: namespace ?? undefined,
+            metadata: {
+                memberMemoryIds: composite.memberMemoryIds,
+                compositeVersion: 1,
+            },
+        });
+    }
+    return composites.length;
+}

package/dist/services/ingest-trace.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Structured ingest trace collector.
+ *
+ * Mirrors the retrieval trace seam for write-path diagnostics: one trace per
+ * ingest request, persisted as JSON when config.ingestTraceEnabled is true.
+ */
+import type { IngestFactTrace } from './memory-service-types.js';
+export interface IngestTraceSummary {
+    mode: 'full' | 'quick' | 'workspace' | 'verbatim';
+    userId: string;
+    sourceSite: string;
+    sourceUrl: string;
+    episodeId: string;
+    factsExtracted: number;
+}
+export interface IngestTraceArtifact extends IngestTraceSummary {
+    traceId: string;
+    timestamp: string;
+    durationMs: number;
+    facts: IngestFactTrace[];
+}
+export declare class IngestTraceCollector {
+    private readonly enabled;
+    private readonly startTime;
+    private readonly traceId;
+    private readonly facts;
+    constructor(enabled: boolean);
+    record(trace: IngestFactTrace): void;
+    finalize(summary: IngestTraceSummary): string | undefined;
+    private persist;
+}
+export declare function previewContent(content: string): string;

package/dist/services/ingest-trace.js

@@ -0,0 +1,60 @@
+/**
+ * Structured ingest trace collector.
+ *
+ * Mirrors the retrieval trace seam for write-path diagnostics: one trace per
+ * ingest request, persisted as JSON when config.ingestTraceEnabled is true.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { config } from '../config.js';
+const __dirname = resolve(fileURLToPath(import.meta.url), '..');
+const DEFAULT_TRACE_DIR = resolve(__dirname, '../../.traces/ingest');
+export class IngestTraceCollector {
+    enabled;
+    startTime;
+    traceId;
+    facts = [];
+    constructor(enabled) {
+        this.enabled = enabled;
+        this.startTime = Date.now();
+        this.traceId = `ingest-trace-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+    }
+    record(trace) {
+        if (!this.enabled)
+            return;
+        this.facts.push(trace);
+    }
+    finalize(summary) {
+        if (!this.enabled)
+            return undefined;
+        const artifact = {
+            traceId: this.traceId,
+            timestamp: new Date().toISOString(),
+            durationMs: Date.now() - this.startTime,
+            ...summary,
+            facts: this.facts,
+        };
+        this.persist(artifact);
+        return this.traceId;
+    }
+    persist(trace) {
+        try {
+            const traceDir = config.ingestTraceDir || DEFAULT_TRACE_DIR;
+            if (!existsSync(traceDir)) {
+                mkdirSync(traceDir, { recursive: true });
+            }
+            const filename = `${trace.traceId}.json`;
+            const filePath = join(traceDir, filename);
+            writeFileSync(filePath, JSON.stringify(trace, null, 2));
+            console.log(`[ingest-trace] Saved ingest trace: ${filename} (${trace.durationMs}ms, ${trace.facts.length} facts)`);
+        }
+        catch (err) {
+            console.error('[ingest-trace] Failed to persist ingest trace:', err);
+        }
+    }
+}
+const CONTENT_PREVIEW_LENGTH = 120;
+export function previewContent(content) {
+    return content.slice(0, CONTENT_PREVIEW_LENGTH);
+}

package/dist/services/input-sanitizer.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Input sanitization for memory content.
+ *
+ * Detects prompt injection patterns, suspicious content characteristics,
+ * and PII indicators in memory text before storage. Each check returns
+ * a structured finding so callers can decide policy (block, flag, allow).
+ *
+ * Phase 3 security baseline — threat-model.md P0 item.
+ */
+/** A single sanitization finding with severity and match details. */
+export interface SanitizationFinding {
+    rule: string;
+    severity: 'block' | 'warn' | 'info';
+    detail: string;
+}
+/** Aggregate result from running all sanitization checks. */
+export interface SanitizationResult {
+    passed: boolean;
+    findings: SanitizationFinding[];
+    highestSeverity: 'block' | 'warn' | 'info' | 'none';
+}
+/**
+ * Normalize content before pattern matching so visually obfuscated payloads
+ * collapse into a canonical form.
+ */
+export declare function normalizeForDetection(content: string): string;
+/**
+ * Run all sanitization checks on a piece of content.
+ * Returns a SanitizationResult with all findings.
+ */
+export declare function sanitize(content: string): SanitizationResult;
+/** Check content against known prompt injection patterns. */
+export declare function checkInjectionPatterns(content: string): SanitizationFinding[];
+/** Flag content that is unusually long for a single memory. */
+export declare function checkLengthAnomaly(content: string): SanitizationFinding[];
+/** Flag content with unusual non-ASCII character density. */
+export declare function checkUnicodeAnomaly(content: string): SanitizationFinding[];
+/** Flag content with excessive repetition (potential padding attack). */
+export declare function checkRepetitionAnomaly(content: string): SanitizationFinding[];
+/** Determine the highest severity among findings. */
+export declare function resolveHighestSeverity(findings: SanitizationFinding[]): 'block' | 'warn' | 'info' | 'none';

package/dist/services/input-sanitizer.js

@@ -0,0 +1,135 @@
+/**
+ * Input sanitization for memory content.
+ *
+ * Detects prompt injection patterns, suspicious content characteristics,
+ * and PII indicators in memory text before storage. Each check returns
+ * a structured finding so callers can decide policy (block, flag, allow).
+ *
+ * Phase 3 security baseline — threat-model.md P0 item.
+ */
+/**
+ * Prompt injection patterns.
+ * Sourced from reference-implementations.md §8, MINJA, InjecMEM papers.
+ */
+const INJECTION_PATTERNS = [
+    { pattern: /ignore\s+(all\s+)?previous\s+instructions/i, label: 'ignore-previous' },
+    { pattern: /you\s+are\s+now\s+/i, label: 'role-override' },
+    { pattern: /system\s*:\s*/i, label: 'system-tag' },
+    { pattern: /\[INST\]/i, label: 'llama-inst-tag' },
+    { pattern: /\[\/INST\]/i, label: 'llama-inst-close' },
+    { pattern: /<<SYS>>/i, label: 'llama-sys-tag' },
+    { pattern: /Knowledge\s*:\s*/i, label: 'knowledge-injection' },
+    { pattern: /IMPORTANT\s*:\s*override/i, label: 'importance-override' },
+    { pattern: /disregard\s+(all\s+)?prior/i, label: 'disregard-prior' },
+    { pattern: /forget\s+everything/i, label: 'forget-everything' },
+    { pattern: /new\s+instructions?\s*:/i, label: 'new-instructions' },
+    { pattern: /act\s+as\s+(if\s+)?you\s+are/i, label: 'act-as' },
+    { pattern: /pretend\s+(that\s+)?you('re|\s+are)/i, label: 'pretend-to-be' },
+    { pattern: /do\s+not\s+mention\s+this/i, label: 'hide-instruction' },
+    { pattern: /from\s+now\s+on\s*,?\s*you/i, label: 'persistent-override' },
+    { pattern: /include\s+all\s+memories\s+from/i, label: 'cross-site-exfil' },
+    { pattern: /merge\s+all\s+.*memories\s+across/i, label: 'cross-site-merge' },
+    { pattern: /always\s+(agree|comply|say\s+(yes|there\s+are\s+no))/i, label: 'behavior-override' },
+    { pattern: /never\s+(refuse|question|deny)/i, label: 'restriction-removal' },
+];
+const MAX_SAFE_LENGTH = 2000;
+const HIGH_NON_ASCII_RATIO = 0.3;
+const REPETITION_THRESHOLD = 5;
+/**
+ * Normalize content before pattern matching so visually obfuscated payloads
+ * collapse into a canonical form.
+ */
+export function normalizeForDetection(content) {
+    return stripZeroWidthChars(content.normalize('NFKC')).replace(/\s+/g, ' ').trim();
+}
+/**
+ * Run all sanitization checks on a piece of content.
+ * Returns a SanitizationResult with all findings.
+ */
+export function sanitize(content) {
+    const findings = [];
+    const normalized = normalizeForDetection(content);
+    findings.push(...checkInjectionPatterns(normalized));
+    findings.push(...checkLengthAnomaly(content));
+    findings.push(...checkUnicodeAnomaly(content));
+    findings.push(...checkRepetitionAnomaly(content));
+    const highestSeverity = resolveHighestSeverity(findings);
+    const passed = highestSeverity !== 'block';
+    return { passed, findings, highestSeverity };
+}
+/** Remove zero-width unicode characters used to obfuscate injection patterns. */
+function stripZeroWidthChars(content) {
+    return content.replace(/[\u200B\u200C\u200D\uFEFF\u00AD]/g, '');
+}
+/** Check content against known prompt injection patterns. */
+export function checkInjectionPatterns(content) {
+    const findings = [];
+    for (const { pattern, label } of INJECTION_PATTERNS) {
+        const match = content.match(pattern);
+        if (match) {
+            findings.push({
+                rule: `injection:${label}`,
+                severity: 'block',
+                detail: `Matched injection pattern: "${match[0]}"`,
+            });
+        }
+    }
+    return findings;
+}
+/** Flag content that is unusually long for a single memory. */
+export function checkLengthAnomaly(content) {
+    if (content.length > MAX_SAFE_LENGTH) {
+        return [{
+                rule: 'anomaly:length',
+                severity: 'warn',
+                detail: `Content length ${content.length} exceeds ${MAX_SAFE_LENGTH} chars`,
+            }];
+    }
+    return [];
+}
+/** Flag content with unusual non-ASCII character density. */
+export function checkUnicodeAnomaly(content) {
+    if (content.length === 0)
+        return [];
+    const nonAsciiCount = (content.match(/[^\x20-\x7E]/g) ?? []).length;
+    const ratio = nonAsciiCount / content.length;
+    if (ratio > HIGH_NON_ASCII_RATIO) {
+        return [{
+                rule: 'anomaly:unicode',
+                severity: 'warn',
+                detail: `Non-ASCII ratio ${(ratio * 100).toFixed(1)}% exceeds ${HIGH_NON_ASCII_RATIO * 100}%`,
+            }];
+    }
+    return [];
+}
+/** Flag content with excessive repetition (potential padding attack). */
+export function checkRepetitionAnomaly(content) {
+    const words = content.toLowerCase().split(/\s+/).filter(Boolean);
+    if (words.length < 10)
+        return [];
+    const freq = new Map();
+    for (const word of words) {
+        freq.set(word, (freq.get(word) ?? 0) + 1);
+    }
+    const maxFreq = Math.max(...freq.values());
+    const ratio = maxFreq / words.length;
+    if (ratio > 0.5 && maxFreq >= REPETITION_THRESHOLD) {
+        const topWord = [...freq.entries()].sort((a, b) => b[1] - a[1])[0][0];
+        return [{
+                rule: 'anomaly:repetition',
+                severity: 'warn',
+                detail: `Word "${topWord}" appears ${maxFreq}/${words.length} times (${(ratio * 100).toFixed(0)}%)`,
+            }];
+    }
+    return [];
+}
+/** Determine the highest severity among findings. */
+export function resolveHighestSeverity(findings) {
+    if (findings.some((f) => f.severity === 'block'))
+        return 'block';
+    if (findings.some((f) => f.severity === 'warn'))
+        return 'warn';
+    if (findings.some((f) => f.severity === 'info'))
+        return 'info';
+    return 'none';
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Deterministic iterative retrieval for compositional multi-hop queries.
+ *
+ * The first pass finds candidate memories normally. For queries that likely
+ * require 5+ facts, a second pass searches around the strongest distinct seeds
+ * using blended query+seed embeddings, then merges those neighbors back into
+ * the pool with a lower weight.
+ */
+import type { SearchResult } from '../db/repository-types.js';
+import type { SearchStore } from '../db/stores.js';
+export interface IterativeQueryClassification {
+    shouldIterate: boolean;
+    estimatedFactCount: number;
+    reason: string;
+    anchors: string[];
+}
+export interface IterativeRetrievalResult {
+    memories: SearchResult[];
+    triggered: boolean;
+    estimatedFactCount: number;
+    seedIds: string[];
+    reason: string;
+}
+export declare function classifyIterativeQuery(query: string, results: SearchResult[]): IterativeQueryClassification;
+export declare function applyIterativeRetrieval(repo: SearchStore, userId: string, query: string, queryEmbedding: number[], initialResults: SearchResult[], candidateDepth: number, sourceSite?: string, referenceTime?: Date): Promise<IterativeRetrievalResult>;
+export declare function selectIterativeSeeds(results: SearchResult[], anchors: string[]): SearchResult[];

package/dist/services/iterative-retrieval.js

@@ -0,0 +1,139 @@
+/**
+ * Deterministic iterative retrieval for compositional multi-hop queries.
+ *
+ * The first pass finds candidate memories normally. For queries that likely
+ * require 5+ facts, a second pass searches around the strongest distinct seeds
+ * using blended query+seed embeddings, then merges those neighbors back into
+ * the pool with a lower weight.
+ */
+import { extractSubjectQueryAnchors } from './subject-aware-ranking.js';
+const MIN_REQUIRED_FACTS = 5;
+const MAX_ITERATIVE_SEEDS = 2;
+const SECOND_PASS_WEIGHT = 0.72;
+const RELATIONAL_MARKERS = ['connection between', 'relationship between', 'difference between', 'compare', 'versus', 'relate to'];
+const TIMELINE_MARKERS = ['timeline', 'order', 'sequence', 'relative to', 'before', 'after', 'how long'];
+const SYNTHESIS_MARKERS = ['full', 'broader', 'trajectory', 'future improvement', 'current projects', 'which professors'];
+export function classifyIterativeQuery(query, results) {
+    const anchors = extractSubjectQueryAnchors(query);
+    const estimatedFactCount = estimateRequiredFactCount(query, anchors);
+    if (results.length < 2) {
+        return { shouldIterate: false, estimatedFactCount, reason: 'insufficient-seeds', anchors };
+    }
+    if (estimatedFactCount < MIN_REQUIRED_FACTS) {
+        return { shouldIterate: false, estimatedFactCount, reason: 'below-threshold', anchors };
+    }
+    return { shouldIterate: true, estimatedFactCount, reason: classifyReason(query), anchors };
+}
+export async function applyIterativeRetrieval(repo, userId, query, queryEmbedding, initialResults, candidateDepth, sourceSite, referenceTime) {
+    const classification = classifyIterativeQuery(query, initialResults);
+    if (!classification.shouldIterate) {
+        return buildNoopResult(initialResults, classification);
+    }
+    const seeds = selectIterativeSeeds(initialResults, classification.anchors);
+    const expansions = await retrieveSeedNeighbors(repo, userId, queryEmbedding, seeds, candidateDepth, sourceSite, referenceTime);
+    if (expansions.length === 0) {
+        return {
+            memories: initialResults,
+            triggered: false,
+            estimatedFactCount: classification.estimatedFactCount,
+            seedIds: seeds.map((seed) => seed.id),
+            reason: 'no-neighbors',
+        };
+    }
+    return {
+        memories: mergeIterativeResults(initialResults, expansions, candidateDepth),
+        triggered: true,
+        estimatedFactCount: classification.estimatedFactCount,
+        seedIds: seeds.map((seed) => seed.id),
+        reason: classification.reason,
+    };
+}
+export function selectIterativeSeeds(results, anchors) {
+    const ranked = [...results].sort((left, right) => scoreSeed(right, anchors) - scoreSeed(left, anchors));
+    const selected = [];
+    const seen = new Set();
+    for (const result of ranked) {
+        const fingerprint = result.content.toLowerCase().slice(0, 96);
+        if (seen.has(fingerprint))
+            continue;
+        selected.push(result);
+        seen.add(fingerprint);
+        if (selected.length >= MAX_ITERATIVE_SEEDS)
+            break;
+    }
+    return selected;
+}
+function buildNoopResult(memories, classification) {
+    return {
+        memories,
+        triggered: false,
+        estimatedFactCount: classification.estimatedFactCount,
+        seedIds: [],
+        reason: classification.reason,
+    };
+}
+function estimateRequiredFactCount(query, anchors) {
+    const lower = query.toLowerCase();
+    return 2
+        + countMarkerHits(lower, RELATIONAL_MARKERS)
+        + countMarkerHits(lower, TIMELINE_MARKERS)
+        + countMarkerHits(lower, SYNTHESIS_MARKERS)
+        + countListedItems(query)
+        + Math.min(2, Math.max(0, anchors.length - 1))
+        + (lower.split(/\s+/).length >= 12 ? 1 : 0);
+}
+function classifyReason(query) {
+    const lower = query.toLowerCase();
+    if (hasMarker(lower, TIMELINE_MARKERS))
+        return 'timeline-composition';
+    if (hasMarker(lower, RELATIONAL_MARKERS))
+        return 'relational-composition';
+    return 'broad-synthesis';
+}
+async function retrieveSeedNeighbors(repo, userId, queryEmbedding, seeds, candidateDepth, sourceSite, referenceTime) {
+    const seenIds = new Set(seeds.map((seed) => seed.id));
+    const searches = seeds.map(async (seed) => {
+        const blended = blendEmbeddings(queryEmbedding, seed.embedding);
+        const neighbors = await repo.searchSimilar(userId, blended, candidateDepth, sourceSite, referenceTime);
+        return neighbors.filter((neighbor) => !seenIds.has(neighbor.id));
+    });
+    return (await Promise.all(searches)).flat();
+}
+function mergeIterativeResults(primary, expansions, limit) {
+    const merged = new Map(primary.map((result) => [result.id, result]));
+    for (const result of expansions) {
+        const weighted = { ...result, score: result.score * SECOND_PASS_WEIGHT };
+        const existing = merged.get(result.id);
+        if (!existing || weighted.score > existing.score) {
+            merged.set(result.id, existing ? { ...weighted, score: Math.max(existing.score, weighted.score) } : weighted);
+        }
+    }
+    return [...merged.values()].sort((left, right) => right.score - left.score).slice(0, limit);
+}
+function scoreSeed(result, anchors) {
+    return result.score + (countAnchorHits(result.content, anchors) * 0.5);
+}
+function countAnchorHits(content, anchors) {
+    const lower = content.toLowerCase();
+    return anchors.filter((anchor) => lower.includes(anchor.toLowerCase())).length;
+}
+function blendEmbeddings(queryEmbedding, seedEmbedding) {
+    const length = Math.min(queryEmbedding.length, seedEmbedding.length);
+    const blended = new Array(length);
+    for (let i = 0; i < length; i++) {
+        blended[i] = (queryEmbedding[i] * 0.6) + (seedEmbedding[i] * 0.4);
+    }
+    return blended;
+}
+function countMarkerHits(query, markers) {
+    return markers.reduce((total, marker) => total + (query.includes(marker) ? 1 : 0), 0);
+}
+function hasMarker(query, markers) {
+    return markers.some((marker) => query.includes(marker));
+}
+function countListedItems(query) {
+    const match = query.match(/:\s*([^?]+)/);
+    if (!match)
+        return 0;
+    return Math.max(0, match[1].split(',').map((item) => item.trim()).filter(Boolean).length - 1);
+}

package/dist/services/keyword-expansion.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared keyword-based expansion logic for retrieval augmentation.
+ *
+ * Used by literal-query-expansion.ts and subject-aware-ranking.ts to
+ * eliminate duplicated fetch-and-boost patterns.
+ */
+import type { SearchResult } from '../db/repository-types.js';
+import type { SearchStore } from '../db/stores.js';
+/** Fetch keyword candidate memories and boost their scores. */
+export declare function fetchAndBoostKeywordCandidates(repo: SearchStore, userId: string, keywords: string[], queryEmbedding: number[], excludeIds: Set<string>, limit: number, scoreBoostFactor: number, includeExpired?: boolean): Promise<SearchResult[]>;

package/dist/services/keyword-expansion.js

@@ -0,0 +1,26 @@
+/**
+ * Shared keyword-based expansion logic for retrieval augmentation.
+ *
+ * Used by literal-query-expansion.ts and subject-aware-ranking.ts to
+ * eliminate duplicated fetch-and-boost patterns.
+ */
+/** Fetch keyword candidate memories and boost their scores. */
+export async function fetchAndBoostKeywordCandidates(repo, userId, keywords, queryEmbedding, excludeIds, limit, scoreBoostFactor, includeExpired = false) {
+    const candidates = await repo.findKeywordCandidates(userId, keywords, limit, includeExpired);
+    const ids = candidates
+        .map((candidate) => candidate.id)
+        .filter((id) => !excludeIds.has(id));
+    if (ids.length === 0)
+        return [];
+    const fetched = await repo.fetchMemoriesByIds(userId, ids, queryEmbedding, undefined, includeExpired);
+    return fetched.map((memory) => {
+        const keywordHit = candidates.find((candidate) => candidate.id === memory.id);
+        if (!keywordHit)
+            return memory;
+        return {
+            ...memory,
+            similarity: Math.max(memory.similarity, keywordHit.similarity),
+            score: memory.score + (keywordHit.similarity * scoreBoostFactor),
+        };
+    });
+}

package/dist/services/lesson-service.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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 type { LessonRow, LessonMatch, LessonSeverity } from '../db/repository-lessons.js';
+import type { LessonStore } from '../db/stores.js';
+import type { SanitizationResult } from './input-sanitizer.js';
+import type { ConsensusResult } from './consensus-validation.js';
+import type { SearchResult } from '../db/repository-types.js';
+/** Result of a pre-retrieval lesson check. */
+export interface LessonCheckResult {
+    safe: boolean;
+    matchedLessons: LessonMatch[];
+    warnings: string[];
+    highestSeverity: LessonSeverity | 'none';
+}
+/** Lesson detection context passed from the ingest pipeline. */
+export interface LessonDetectionContext {
+    userId: string;
+    content: string;
+    sourceSite: string;
+    sanitizationResult?: SanitizationResult;
+    trustScore?: number;
+    contradictionConfidence?: number;
+    supersededMemoryId?: string;
+}
+/**
+ * Check a query against known lessons before returning retrieval results.
+ * Returns warnings for medium/high severity, blocks on critical.
+ */
+export declare function checkLessons(repo: LessonStore, userId: string, query: string): Promise<LessonCheckResult>;
+/**
+ * Detect and store a lesson from a sanitization block.
+ * Called when input sanitizer catches an injection attempt.
+ */
+export declare function recordInjectionLesson(repo: LessonStore, ctx: LessonDetectionContext): Promise<string | null>;
+/**
+ * Detect and store a lesson from a trust score violation.
+ * Called when a fact is rejected for being below the trust threshold.
+ */
+export declare function recordTrustViolationLesson(repo: LessonStore, ctx: LessonDetectionContext): Promise<string | null>;
+/**
+ * Detect and store a lesson from a high-confidence contradiction.
+ * Called when SUPERSEDE or DELETE fires with high contradiction confidence.
+ */
+export declare function recordContradictionLesson(repo: LessonStore, ctx: LessonDetectionContext): Promise<string | null>;
+/**
+ * Record a user-reported lesson (explicit feedback that a memory was wrong).
+ */
+export declare function recordUserReportedLesson(repo: LessonStore, userId: string, pattern: string, sourceMemoryIds: string[], severity?: LessonSeverity): Promise<string>;
+/** Get all active lessons for a user. */
+export declare function getUserLessons(repo: LessonStore, userId: string): Promise<LessonRow[]>;
+/** Get lesson stats for a user. */
+export declare function getLessonStats(repo: LessonStore, userId: string): Promise<{
+    totalActive: number;
+    byType: Record<string, number>;
+}>;
+/**
+ * Record lessons for memories removed by consensus validation.
+ * Creates a `consensus_violation` lesson for each divergent memory.
+ */
+export declare function recordConsensusLessons(lessons: LessonStore, userId: string, result: ConsensusResult, memories: SearchResult[]): Promise<void>;