@atomicmemory/core 1.0.0

package/dist/services/chunked-extraction.js

@@ -0,0 +1,108 @@
+/**
+ * Chunked extraction — splits conversations into overlapping turn windows
+ * before extracting facts. Helps smaller LLMs (e.g. qwen3:8b) that struggle
+ * with long contexts by giving them focused 3-4 turn windows instead of the
+ * full conversation.
+ *
+ * Each chunk includes a session date header and overlap with the previous
+ * chunk to preserve cross-turn context. Facts are deduplicated across chunks
+ * using embedding similarity.
+ */
+import { extractFacts } from './extraction.js';
+import { cachedExtractFacts } from './extraction-cache.js';
+import { cosineSimilarity, embedText } from './embedding.js';
+const DEDUP_SIMILARITY_THRESHOLD = 0.92;
+/**
+ * Split conversation text into overlapping turn-based chunks.
+ * Expects format: "[Session date: YYYY-MM-DD]\nSpeaker: text\nSpeaker: text\n..."
+ */
+function chunkConversation(conversationText, chunkSize, overlap) {
+    const lines = conversationText.split('\n');
+    // Extract session header (first line if it starts with "[Session")
+    let header = '';
+    let turnLines = [];
+    if (lines[0]?.startsWith('[Session')) {
+        header = lines[0];
+        turnLines = lines.slice(1).filter((l) => l.trim().length > 0);
+    }
+    else {
+        turnLines = lines.filter((l) => l.trim().length > 0);
+    }
+    // Each turn is a line matching "Speaker: text"
+    const turns = turnLines.filter((l) => /^\w[\w\s]*:/.test(l));
+    if (turns.length <= chunkSize) {
+        return [conversationText];
+    }
+    const chunks = [];
+    const step = Math.max(1, chunkSize - overlap);
+    for (let i = 0; i < turns.length; i += step) {
+        const chunkTurns = turns.slice(i, i + chunkSize);
+        if (chunkTurns.length === 0)
+            break;
+        const chunkText = header
+            ? `${header}\n${chunkTurns.join('\n')}`
+            : chunkTurns.join('\n');
+        chunks.push(chunkText);
+        if (i + chunkSize >= turns.length)
+            break;
+    }
+    return chunks;
+}
+/**
+ * Extract facts from each chunk and deduplicate across chunks.
+ * Uses embedding similarity to detect duplicate facts from overlapping windows.
+ */
+export async function chunkedExtractFacts(conversationText, options = {}, chunking) {
+    const chunks = chunkConversation(conversationText, chunking.chunkSizeTurns, chunking.chunkOverlapTurns);
+    if (chunks.length <= 1) {
+        return chunking.extractionCacheEnabled
+            ? cachedExtractFacts(conversationText, options)
+            : extractFacts(conversationText, options);
+    }
+    // Extract facts from each chunk
+    const allFacts = [];
+    for (const chunk of chunks) {
+        const facts = chunking.extractionCacheEnabled
+            ? await cachedExtractFacts(chunk, options)
+            : await extractFacts(chunk, options);
+        allFacts.push(...facts);
+    }
+    if (allFacts.length === 0)
+        return [];
+    // Deduplicate using embedding similarity
+    return deduplicateFacts(allFacts);
+}
+/**
+ * Remove near-duplicate facts by comparing embeddings.
+ * Keeps the first occurrence (from earlier chunks) when duplicates found.
+ */
+async function deduplicateFacts(facts) {
+    if (facts.length <= 1)
+        return facts;
+    const embeddings = await Promise.all(facts.map((f) => embedText(f.fact)));
+    const kept = markDuplicates(facts, embeddings);
+    return facts.filter((_, i) => kept[i]);
+}
+/**
+ * Pairwise comparison to mark near-duplicate facts.
+ * Keeps the higher-importance fact when duplicates are found.
+ */
+function markDuplicates(facts, embeddings) {
+    const kept = new Array(facts.length).fill(true);
+    for (let i = 0; i < facts.length; i++) {
+        if (!kept[i])
+            continue;
+        for (let j = i + 1; j < facts.length; j++) {
+            if (!kept[j])
+                continue;
+            if (cosineSimilarity(embeddings[i], embeddings[j]) < DEDUP_SIMILARITY_THRESHOLD)
+                continue;
+            if (facts[j].importance > facts[i].importance) {
+                kept[i] = false;
+                break;
+            }
+            kept[j] = false;
+        }
+    }
+    return kept;
+}

package/dist/services/claim-slotting.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Deterministic claim slot helpers.
+ * Slots only form for relation-backed facts whose entities already resolve to
+ * canonical IDs. This gives the temporal layer a stable overwrite target
+ * without guessing semantics for every free-form sentence.
+ */
+import { type RelationType, type EntityType } from '../db/repository-types.js';
+import { type ExtractedRelation } from './extraction.js';
+export interface CanonicalEntityRef {
+    extractedName: string;
+    entityId: string;
+    canonicalName: string;
+    entityType: EntityType;
+}
+export interface ClaimSlotDescriptor {
+    slotKey: string;
+    subjectEntityId: string;
+    relationType: RelationType;
+    objectEntityId: string;
+}
+export interface PersistedRelationSlot {
+    sourceEntityId: string;
+    targetEntityId: string;
+    relationType: RelationType;
+}
+export declare function buildRelationClaimSlot(relations: ExtractedRelation[], canonicalEntities: Map<string, CanonicalEntityRef>): ClaimSlotDescriptor | null;
+export declare function buildPersistedRelationClaimSlot(relations: PersistedRelationSlot[]): ClaimSlotDescriptor | null;

package/dist/services/claim-slotting.js

@@ -0,0 +1,38 @@
+/**
+ * Deterministic claim slot helpers.
+ * Slots only form for relation-backed facts whose entities already resolve to
+ * canonical IDs. This gives the temporal layer a stable overwrite target
+ * without guessing semantics for every free-form sentence.
+ */
+export function buildRelationClaimSlot(relations, canonicalEntities) {
+    const candidates = relations
+        .map((relation) => buildRelationSlotCandidate(relation, canonicalEntities))
+        .filter((candidate) => candidate !== null)
+        .sort((left, right) => left.slotKey.localeCompare(right.slotKey));
+    return candidates[0] ?? null;
+}
+export function buildPersistedRelationClaimSlot(relations) {
+    const candidates = relations
+        .filter((relation) => relation.sourceEntityId !== relation.targetEntityId)
+        .map((relation) => ({
+        slotKey: `relation:${relation.sourceEntityId}:${relation.relationType}:${relation.targetEntityId}`,
+        subjectEntityId: relation.sourceEntityId,
+        relationType: relation.relationType,
+        objectEntityId: relation.targetEntityId,
+    }))
+        .sort((left, right) => left.slotKey.localeCompare(right.slotKey));
+    return candidates[0] ?? null;
+}
+function buildRelationSlotCandidate(relation, canonicalEntities) {
+    const source = canonicalEntities.get(relation.source.toLowerCase());
+    const target = canonicalEntities.get(relation.target.toLowerCase());
+    if (!source || !target || source.entityId === target.entityId) {
+        return null;
+    }
+    return {
+        slotKey: `relation:${source.entityId}:${relation.type}:${target.entityId}`,
+        subjectEntityId: source.entityId,
+        relationType: relation.type,
+        objectEntityId: target.entityId,
+    };
+}

package/dist/services/claude-code-llm.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Claude Code Agent SDK-backed LLM provider.
+ *
+ * This provider is intended for local developer setups where the `claude`
+ * CLI is already authenticated. It disables tools, MCP servers, settings,
+ * project context, and session persistence so extraction stays close to a
+ * one-turn chat completion instead of becoming an agent run.
+ */
+import type { ChatMessage, ChatOptions, LLMProvider } from './llm.js';
+import { type WriteCostEventConfig } from './cost-telemetry.js';
+export interface ClaudeCodeLLMConfig extends WriteCostEventConfig {
+    llmProvider: 'claude-code';
+    llmModel: string;
+}
+export declare class ClaudeCodeLLM implements LLMProvider {
+    private readonly config;
+    constructor(config: ClaudeCodeLLMConfig);
+    chat(messages: ChatMessage[], options?: ChatOptions): Promise<string>;
+}

package/dist/services/claude-code-llm.js

@@ -0,0 +1,96 @@
+/**
+ * Claude Code Agent SDK-backed LLM provider.
+ *
+ * This provider is intended for local developer setups where the `claude`
+ * CLI is already authenticated. It disables tools, MCP servers, settings,
+ * project context, and session persistence so extraction stays close to a
+ * one-turn chat completion instead of becoming an agent run.
+ */
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { estimateCostUsd, getCostStage, summarizeUsage, writeCostEvent, } from './cost-telemetry.js';
+export class ClaudeCodeLLM {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async chat(messages, options = {}) {
+        const started = performance.now();
+        const result = await runClaudeCodeQuery(buildPrompt(messages), buildClaudeCodeOptions(messages, this.config.llmModel, options));
+        if (result.subtype !== 'success') {
+            throw new Error(`Claude Code LLM failed: ${result.errors.join('; ')}`);
+        }
+        recordClaudeCodeCost(this.config, result, started);
+        return result.result.trim();
+    }
+}
+function buildPrompt(messages) {
+    return messages
+        .filter((message) => message.role !== 'system')
+        .map((message) => `${message.role.toUpperCase()}:\n${message.content}`)
+        .join('\n\n')
+        .trim();
+}
+function buildClaudeCodeOptions(messages, model, options) {
+    const systemPrompt = buildSystemPrompt(messages, options);
+    return {
+        ...(model ? { model } : {}),
+        ...(systemPrompt ? { systemPrompt } : {}),
+        tools: [],
+        mcpServers: {},
+        settingSources: [],
+        persistSession: false,
+        permissionMode: 'dontAsk',
+        maxTurns: 1,
+    };
+}
+function buildSystemPrompt(messages, options) {
+    const system = messages
+        .filter((message) => message.role === 'system')
+        .map((message) => message.content)
+        .join('\n\n')
+        .trim();
+    if (!options.jsonMode)
+        return system;
+    return [system, 'Return only valid JSON. Do not include markdown fences or commentary.']
+        .filter(Boolean)
+        .join('\n\n');
+}
+async function runClaudeCodeQuery(prompt, options) {
+    let result = null;
+    try {
+        for await (const message of query({ prompt, options })) {
+            if (message.type === 'result')
+                result = message;
+        }
+    }
+    catch (error) {
+        throw new Error('Claude Code LLM failed to run. Confirm `claude` is installed and authenticated: ' +
+            errorMessage(error));
+    }
+    if (!result)
+        throw new Error('Claude Code LLM ended without a result message');
+    return result;
+}
+function recordClaudeCodeCost(config, result, started) {
+    const usage = summarizeUsage(sumModelUsage(result.modelUsage, 'inputTokens'), sumModelUsage(result.modelUsage, 'outputTokens'), null);
+    const model = config.llmModel || Object.keys(result.modelUsage)[0] || 'claude-code';
+    writeCostEvent({
+        stage: getCostStage(),
+        provider: config.llmProvider,
+        model,
+        requestKind: 'chat',
+        durationMs: performance.now() - started,
+        cacheHit: false,
+        inputTokens: usage.inputTokens ?? null,
+        outputTokens: usage.outputTokens ?? null,
+        totalTokens: usage.totalTokens ?? null,
+        estimatedCostUsd: result.total_cost_usd ?? estimateCostUsd(config.llmProvider, model, usage),
+    }, config);
+}
+function sumModelUsage(usage, field) {
+    const total = Object.values(usage).reduce((sum, item) => sum + (item[field] ?? 0), 0);
+    return total > 0 ? total : null;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Composite/member deduplication for injection packaging.
+ *
+ * Two strategies:
+ *
+ * 1. `deduplicateCompositeMembersHard` — tiered mode: if a composite and its
+ *    member atomics both appear, keep the composite and drop covered atomics.
+ *
+ * 2. `deduplicateCompositeMembersSoft` — flat/default mode: use a coverage-
+ *    ratio threshold. If the selected atomics already cover ≥60% of a
+ *    composite's members, suppress the composite (the atomics are more
+ *    precise). Otherwise keep both.
+ *
+ * See: design/composite-vs-atomic-retrieval-contract-2026-03-27.md §Dedup rule
+ */
+import type { SearchResult } from '../db/repository-types.js';
+import type { RetrievalMode } from './memory-service-types.js';
+import type { TraceCollector } from './retrieval-trace.js';
+/**
+ * Hard dedup for tiered mode: composites win, covered atomics are dropped.
+ * This is the existing behavior extracted from memory-service.ts.
+ */
+export declare function deduplicateCompositeMembersHard(memories: SearchResult[]): SearchResult[];
+/**
+ * Soft dedup for flat/default mode: suppress composites when selected atomics
+ * already cover a high fraction of the composite's members.
+ *
+ * Logic:
+ *   coverage = |composite.memberIds ∩ selectedAtomicIds| / |composite.memberIds|
+ *   if coverage ≥ threshold → suppress the composite (atomics are enough)
+ *   if coverage < threshold → keep the composite (it adds uncovered content)
+ *
+ * Atomics are never suppressed — they are the precision layer.
+ */
+export declare function deduplicateCompositeMembersSoft(memories: SearchResult[], coverageThreshold?: number): SearchResult[];
+/**
+ * Flat-mode packaging policy for precision queries. If the query asks for a
+ * specific current or direct factual answer, any composite that overlaps with
+ * already-retrieved atomics is treated as redundant and removed.
+ *
+ * Broad queries still use the softer coverage-ratio threshold because
+ * compression is usually beneficial there.
+ */
+export declare function deduplicateCompositeMembersForFlatQuery(memories: SearchResult[], query: string, coverageThreshold?: number): SearchResult[];
+export declare function prefersAtomicFlatPackaging(query: string): boolean;
+/**
+ * Apply flat-mode composite dedup and record the dedup as a trace stage
+ * if the result set changed. No-op for non-flat modes or empty sets.
+ */
+export declare function applyFlatPackagingPolicy(memories: SearchResult[], query: string, mode: RetrievalMode, trace: TraceCollector): SearchResult[];

package/dist/services/composite-dedup.js

@@ -0,0 +1,153 @@
+/**
+ * Composite/member deduplication for injection packaging.
+ *
+ * Two strategies:
+ *
+ * 1. `deduplicateCompositeMembersHard` — tiered mode: if a composite and its
+ *    member atomics both appear, keep the composite and drop covered atomics.
+ *
+ * 2. `deduplicateCompositeMembersSoft` — flat/default mode: use a coverage-
+ *    ratio threshold. If the selected atomics already cover ≥60% of a
+ *    composite's members, suppress the composite (the atomics are more
+ *    precise). Otherwise keep both.
+ *
+ * See: design/composite-vs-atomic-retrieval-contract-2026-03-27.md §Dedup rule
+ */
+import { isCurrentStateQuery } from './current-state-ranking.js';
+const DEFAULT_COVERAGE_THRESHOLD = 0.6;
+const BROAD_QUERY_MARKERS = [
+    'summarize',
+    'summary',
+    'overview',
+    'what should the assistant know',
+    'tell me about',
+    'recap',
+    'background',
+    'context',
+];
+const DIRECT_QUERY_STARTERS = ['who ', 'what ', 'which ', 'where '];
+const MAX_DIRECT_QUERY_WORDS = 10;
+/**
+ * Hard dedup for tiered mode: composites win, covered atomics are dropped.
+ * This is the existing behavior extracted from memory-service.ts.
+ */
+export function deduplicateCompositeMembersHard(memories) {
+    const composites = memories.filter((m) => m.memory_type === 'composite');
+    if (composites.length === 0)
+        return memories;
+    const coveredIds = new Set();
+    for (const composite of composites) {
+        const memberIds = composite.metadata?.memberMemoryIds;
+        if (Array.isArray(memberIds)) {
+            for (const id of memberIds) {
+                if (typeof id === 'string')
+                    coveredIds.add(id);
+            }
+        }
+    }
+    if (coveredIds.size === 0)
+        return memories;
+    return memories.filter((m) => m.memory_type === 'composite' || !coveredIds.has(m.id));
+}
+/**
+ * Soft dedup for flat/default mode: suppress composites when selected atomics
+ * already cover a high fraction of the composite's members.
+ *
+ * Logic:
+ *   coverage = |composite.memberIds ∩ selectedAtomicIds| / |composite.memberIds|
+ *   if coverage ≥ threshold → suppress the composite (atomics are enough)
+ *   if coverage < threshold → keep the composite (it adds uncovered content)
+ *
+ * Atomics are never suppressed — they are the precision layer.
+ */
+export function deduplicateCompositeMembersSoft(memories, coverageThreshold = DEFAULT_COVERAGE_THRESHOLD) {
+    const composites = memories.filter((m) => m.memory_type === 'composite');
+    if (composites.length === 0)
+        return memories;
+    const atomicIds = new Set(memories
+        .filter((m) => m.memory_type !== 'composite')
+        .map((m) => m.id));
+    if (atomicIds.size === 0)
+        return memories;
+    const suppressedCompositeIds = new Set();
+    for (const composite of composites) {
+        const memberIds = composite.metadata?.memberMemoryIds;
+        if (!Array.isArray(memberIds) || memberIds.length === 0)
+            continue;
+        const validMemberIds = memberIds.filter((id) => typeof id === 'string');
+        if (validMemberIds.length === 0)
+            continue;
+        const coveredCount = validMemberIds.filter((id) => atomicIds.has(id)).length;
+        const coverageRatio = coveredCount / validMemberIds.length;
+        if (coverageRatio >= coverageThreshold) {
+            suppressedCompositeIds.add(composite.id);
+        }
+    }
+    if (suppressedCompositeIds.size === 0)
+        return memories;
+    return memories.filter((m) => !suppressedCompositeIds.has(m.id));
+}
+/**
+ * Flat-mode packaging policy for precision queries. If the query asks for a
+ * specific current or direct factual answer, any composite that overlaps with
+ * already-retrieved atomics is treated as redundant and removed.
+ *
+ * Broad queries still use the softer coverage-ratio threshold because
+ * compression is usually beneficial there.
+ */
+export function deduplicateCompositeMembersForFlatQuery(memories, query, coverageThreshold = DEFAULT_COVERAGE_THRESHOLD) {
+    if (!prefersAtomicFlatPackaging(query)) {
+        return deduplicateCompositeMembersSoft(memories, coverageThreshold);
+    }
+    return suppressOverlappingComposites(memories);
+}
+export function prefersAtomicFlatPackaging(query) {
+    const normalized = normalizeQuery(query);
+    if (BROAD_QUERY_MARKERS.some((marker) => normalized.includes(marker)))
+        return false;
+    if (isCurrentStateQuery(query))
+        return true;
+    return DIRECT_QUERY_STARTERS.some((starter) => normalized.startsWith(starter))
+        && normalized.split(/\s+/).length <= MAX_DIRECT_QUERY_WORDS;
+}
+function suppressOverlappingComposites(memories) {
+    const atomicIds = new Set(memories
+        .filter((memory) => memory.memory_type !== 'composite')
+        .map((memory) => memory.id));
+    if (atomicIds.size === 0)
+        return memories;
+    const overlappingCompositeIds = new Set(memories
+        .filter((memory) => memory.memory_type === 'composite')
+        .filter((memory) => parseMemberIds(memory).some((id) => atomicIds.has(id)))
+        .map((memory) => memory.id));
+    if (overlappingCompositeIds.size === 0)
+        return memories;
+    return memories.filter((memory) => !overlappingCompositeIds.has(memory.id));
+}
+function normalizeQuery(query) {
+    return query.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+function parseMemberIds(memory) {
+    const candidate = memory.metadata?.memberMemoryIds;
+    if (!Array.isArray(candidate))
+        return [];
+    return candidate.filter((id) => typeof id === 'string');
+}
+/**
+ * Apply flat-mode composite dedup and record the dedup as a trace stage
+ * if the result set changed. No-op for non-flat modes or empty sets.
+ */
+export function applyFlatPackagingPolicy(memories, query, mode, trace) {
+    if (mode !== 'flat' || memories.length === 0)
+        return memories;
+    const packaged = deduplicateCompositeMembersForFlatQuery(memories, query);
+    if (packaged.length === memories.length && packaged[0]?.id === memories[0]?.id) {
+        return memories;
+    }
+    trace.stage('flat-packaging-dedup', packaged, {
+        removedIds: memories
+            .map((memory) => memory.id)
+            .filter((id) => !packaged.some((memory) => memory.id === id)),
+    });
+    return packaged;
+}

package/dist/services/composite-grouping.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Composite Memory Grouping — clusters related atomic facts from a single episode
+ * into paragraph-length composite memories that benefit from tiered loading (L0/L1/L2).
+ *
+ * Atomistic extraction produces single-sentence facts (median ~80 chars) where
+ * L1 overviews are identical to L2 content, making tiered retrieval degenerate to
+ * flat mode. Composites bridge this gap: they join related facts into paragraph-length
+ * content that generateL1Overview() can meaningfully compress.
+ *
+ * Algorithm: Greedy single-linkage clustering on cosine similarity of fact embeddings.
+ * Clusters with < minClusterSize members are skipped (no compression benefit).
+ */
+export interface CompositeInput {
+    memoryId: string;
+    content: string;
+    embedding: number[];
+    importance: number;
+    keywords: string[];
+    headline: string;
+}
+export interface CompositeMemory {
+    /** Paragraph joining member facts in importance-descending order. */
+    content: string;
+    /** L0: headline from the most important member fact. */
+    headline: string;
+    /** L1: overview generated from the composite content (first 2-3 sentences). */
+    overview: string;
+    /** Centroid of member fact embeddings. */
+    embedding: number[];
+    /** Max importance across member facts. */
+    importance: number;
+    /** Union of all member keywords, deduplicated. */
+    keywords: string[];
+    /** IDs of the atomic memories grouped into this composite. */
+    memberMemoryIds: string[];
+}
+/**
+ * Group facts from a single episode into composite memories by topic similarity.
+ * Returns only composites with ≥ minClusterSize members.
+ */
+export declare function buildComposites(facts: CompositeInput[]): CompositeMemory[];

package/dist/services/composite-grouping.js

@@ -0,0 +1,111 @@
+/**
+ * Composite Memory Grouping — clusters related atomic facts from a single episode
+ * into paragraph-length composite memories that benefit from tiered loading (L0/L1/L2).
+ *
+ * Atomistic extraction produces single-sentence facts (median ~80 chars) where
+ * L1 overviews are identical to L2 content, making tiered retrieval degenerate to
+ * flat mode. Composites bridge this gap: they join related facts into paragraph-length
+ * content that generateL1Overview() can meaningfully compress.
+ *
+ * Algorithm: Greedy single-linkage clustering on cosine similarity of fact embeddings.
+ * Clusters with < minClusterSize members are skipped (no compression benefit).
+ */
+import { config } from '../config.js';
+import { cosineSimilarity } from './embedding.js';
+import { generateL1Overview } from './tiered-context.js';
+/**
+ * Group facts from a single episode into composite memories by topic similarity.
+ * Returns only composites with ≥ minClusterSize members.
+ */
+export function buildComposites(facts) {
+    if (facts.length < config.compositeMinClusterSize)
+        return [];
+    const clusters = clusterBySimilarity(facts, config.compositeSimilarityThreshold);
+    return clusters
+        .filter((cluster) => cluster.length >= config.compositeMinClusterSize)
+        .map(synthesizeComposite);
+}
+/**
+ * Greedy single-linkage clustering: assign each fact to the most similar
+ * existing cluster (by centroid), or start a new cluster if below threshold.
+ *
+ * Clusters are capped at compositeMaxClusterSize to prevent "everything-bagel"
+ * composites where centroid drift causes unrelated facts to cluster together.
+ */
+function clusterBySimilarity(facts, threshold) {
+    const clusters = [];
+    const centroids = [];
+    const maxSize = config.compositeMaxClusterSize;
+    for (const fact of facts) {
+        let bestClusterIndex = -1;
+        let bestSimilarity = -1;
+        for (let i = 0; i < centroids.length; i++) {
+            if (clusters[i].length >= maxSize)
+                continue;
+            const sim = cosineSimilarity(fact.embedding, centroids[i]);
+            if (sim > bestSimilarity) {
+                bestSimilarity = sim;
+                bestClusterIndex = i;
+            }
+        }
+        if (bestClusterIndex >= 0 && bestSimilarity >= threshold) {
+            clusters[bestClusterIndex].push(fact);
+            centroids[bestClusterIndex] = computeCentroid(clusters[bestClusterIndex]);
+        }
+        else {
+            clusters.push([fact]);
+            centroids.push([...fact.embedding]);
+        }
+    }
+    return clusters;
+}
+/** Synthesize a composite memory from a cluster of related facts. */
+function synthesizeComposite(cluster) {
+    const sorted = [...cluster].sort((a, b) => b.importance - a.importance);
+    const content = sorted.map((f) => f.content).join(' ');
+    const headline = sorted[0].headline;
+    const overview = generateL1Overview(content);
+    const embedding = computeCentroid(cluster);
+    const importance = Math.max(...cluster.map((f) => f.importance));
+    const keywords = deduplicateKeywords(cluster.flatMap((f) => f.keywords));
+    const memberMemoryIds = cluster.map((f) => f.memoryId);
+    return {
+        content,
+        headline,
+        overview: overview !== content ? overview : '',
+        embedding,
+        importance,
+        keywords,
+        memberMemoryIds,
+    };
+}
+/** Compute the centroid (element-wise mean) of a set of embeddings. */
+function computeCentroid(facts) {
+    if (facts.length === 0)
+        return [];
+    const dim = facts[0].embedding.length;
+    const sum = new Float64Array(dim);
+    for (const fact of facts) {
+        for (let i = 0; i < dim; i++) {
+            sum[i] += fact.embedding[i];
+        }
+    }
+    const centroid = new Array(dim);
+    for (let i = 0; i < dim; i++) {
+        centroid[i] = sum[i] / facts.length;
+    }
+    return centroid;
+}
+/** Deduplicate keywords preserving original casing of first occurrence. */
+function deduplicateKeywords(keywords) {
+    const seen = new Set();
+    const result = [];
+    for (const kw of keywords) {
+        const lower = kw.toLowerCase();
+        if (!seen.has(lower)) {
+            seen.add(lower);
+            result.push(kw);
+        }
+    }
+    return result;
+}

package/dist/services/composite-staleness.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Composite staleness filtering for retrieval.
+ *
+ * Phase 1 policy from the composite-vs-atomic retrieval contract:
+ * exclude composites from default retrieval if any covered member memory is no
+ * longer active. This catches superseded members (expired), invalidated or
+ * deleted members, and dangling member IDs left behind after deletes.
+ */
+import type { SearchResult } from '../db/repository-types.js';
+interface MemoryLookup {
+    getMemory(id: string, userId: string): Promise<{
+        id: string;
+    } | null>;
+}
+export interface CompositeStalenessResult {
+    filtered: SearchResult[];
+    removedCompositeIds: string[];
+}
+export declare function excludeStaleComposites(repo: MemoryLookup, userId: string, memories: SearchResult[]): Promise<CompositeStalenessResult>;
+export {};