@atomicmemory/core 1.0.0

package/dist/services/memory-service.js

@@ -0,0 +1,225 @@
+/**
+ * Core memory service facade -- delegates to memory-ingest, memory-search, and memory-crud.
+ * Preserves the public API (routes call service.search(), service.quickIngest(), etc.)
+ * while keeping each concern in a focused, testable module.
+ */
+import { config } from '../config.js';
+import { URIResolver } from './atomicmem-uri.js';
+import { performIngest, performQuickIngest, performStoreVerbatim, performWorkspaceIngest } from './memory-ingest.js';
+import { performSearch, performFastSearch, performWorkspaceSearch } from './memory-search.js';
+import * as crud from './memory-crud.js';
+/**
+ * Materialize the {@link MemoryServiceDeps} bundle from constructor
+ * inputs. Extracted so the constructor stays under the workspace
+ * cyclomatic-complexity threshold; the optional-with-fallback chain
+ * lives here, the constructor is just plumbing.
+ */
+function buildDefaultStores(bag) {
+    const { repo, claims } = bag;
+    return {
+        memory: repo,
+        episode: repo,
+        recap: null,
+        search: repo,
+        link: repo,
+        representation: repo,
+        claim: claims,
+        entity: bag.entities ?? null,
+        lesson: bag.lessons ?? null,
+        summaries: null,
+        userProfile: null,
+        entityAttributes: null,
+        reflections: null,
+        reflectionJobs: null,
+        entityCards: null,
+        contradictions: null,
+        beliefEdges: null,
+        entityValues: null,
+        pool: typeof repo.getPool === 'function' ? repo.getPool() : {},
+    };
+}
+// fallow-ignore-next-line complexity
+function buildMemoryServiceDeps(bag) {
+    return {
+        config: bag.runtimeConfig ?? config,
+        stores: bag.stores ?? buildDefaultStores(bag),
+        observationService: bag.observationService ?? null,
+        tllRepository: bag.tllRepository ?? null,
+        firstMentionService: bag.firstMentionService ?? null,
+        uriResolver: new URIResolver(bag.repo, bag.claims),
+        reflectionJobs: bag.stores?.reflectionJobs ?? undefined,
+        reflectEnabled: bag.runtimeConfig?.reflectEnabled ?? false,
+        rawContentStore: bag.rawContentStore ?? null,
+        storeRegistry: bag.storeRegistry,
+    };
+}
+export class MemoryService {
+    repo;
+    claims;
+    deps;
+    constructor(repo, claims, entities, lessons, observationService, runtimeConfig, stores, tllRepository, firstMentionService, 
+    /**
+     * Phase-3 raw-content adapter. Optional so existing call sites and
+     * pointer-only deployments stay unchanged; supplied at composition
+     * time when `rawStorageMode='managed_blob'`.
+     */
+    rawContentStore, 
+    /**
+     * Phase 4a per-row dispatch registry. Optional for existing
+     * call sites; composition-root code passes it when
+     * `RAW_STORAGE_LEGACY_PROVIDERS` is set. Falls back to
+     * `singleStoreRegistry(rawContentStore)` inside `resetBySource`
+     * when absent.
+     */
+    storeRegistry) {
+        this.repo = repo;
+        this.claims = claims;
+        this.deps = buildMemoryServiceDeps({
+            repo, claims, entities, lessons, observationService, runtimeConfig,
+            stores, tllRepository, firstMentionService, rawContentStore, storeRegistry,
+        });
+    }
+    /**
+     * Build a request-scoped deps bundle that swaps in the effective config
+     * for the duration of a single call. Returns the shared `this.deps`
+     * unchanged when no override is supplied (zero-allocation fast path).
+     * All per-fact/per-pipeline helpers already read `deps.config`, so
+     * replacing it at the entry point propagates through the service layer
+     * without mutating shared state.
+     */
+    depsFor(effectiveConfig) {
+        if (!effectiveConfig)
+            return this.deps;
+        return { ...this.deps, config: effectiveConfig };
+    }
+    // --- Ingest ---
+    async ingest(userId, conversationText, sourceSite, sourceUrl = '', sessionTimestamp, effectiveConfig) {
+        return performIngest(this.depsFor(effectiveConfig), userId, conversationText, sourceSite, sourceUrl, sessionTimestamp);
+    }
+    async quickIngest(userId, conversationText, sourceSite, sourceUrl = '', sessionTimestamp, effectiveConfig) {
+        return performQuickIngest(this.depsFor(effectiveConfig), userId, conversationText, sourceSite, sourceUrl, sessionTimestamp);
+    }
+    /**
+     * Store content as a single memory without fact extraction.
+     * Used for user-created contexts (text/file uploads) where
+     * the content should remain as one canonical memory record.
+     */
+    async storeVerbatim(userId, content, sourceSite, sourceUrl = '', metadata, effectiveConfig) {
+        return performStoreVerbatim(this.depsFor(effectiveConfig), userId, content, sourceSite, sourceUrl, metadata);
+    }
+    async workspaceIngest(userId, conversationText, sourceSite, sourceUrl = '', workspace, sessionTimestamp, effectiveConfig) {
+        return performWorkspaceIngest(this.depsFor(effectiveConfig), userId, conversationText, sourceSite, sourceUrl, workspace, sessionTimestamp);
+    }
+    // --- Search (scope-dispatching) ---
+    /** Scope-dispatching search: routes to user or workspace search based on scope.kind. */
+    async scopedSearch(scope, query, options = {}) {
+        const deps = this.depsFor(options.effectiveConfig);
+        if (scope.kind === 'workspace') {
+            const ws = { workspaceId: scope.workspaceId, agentId: scope.agentId };
+            return performWorkspaceSearch(deps, scope.userId, query, ws, {
+                agentScope: scope.agentScope,
+                limit: options.limit,
+                referenceTime: options.referenceTime,
+                retrievalOptions: options.retrievalOptions,
+            });
+        }
+        if (options.fast) {
+            return performFastSearch(deps, scope.userId, query, options.sourceSite, options.limit, options.namespaceScope, options.retrievalOptions);
+        }
+        return performSearch(deps, scope.userId, query, options.sourceSite, options.limit, options.asOf, options.referenceTime, options.namespaceScope, options.retrievalOptions);
+    }
+    /** Scope-dispatching expand with agent visibility enforcement for workspace operations. */
+    async scopedExpand(scope, memoryIds) {
+        if (scope.kind === 'workspace')
+            return crud.expandMemoriesInWorkspace(this.deps, scope.workspaceId, memoryIds, scope.agentId);
+        return crud.expandMemories(this.deps, scope.userId, memoryIds);
+    }
+    /** Scope-dispatching get with agent visibility enforcement for workspace operations. */
+    async scopedGet(scope, id) {
+        if (scope.kind === 'workspace')
+            return crud.getMemoryInWorkspace(this.deps, id, scope.workspaceId, scope.agentId);
+        return crud.getMemory(this.deps, id, scope.userId);
+    }
+    /** Scope-dispatching delete with agent visibility enforcement. Returns false if not found/not visible. */
+    async scopedDelete(scope, id) {
+        if (scope.kind === 'workspace')
+            return crud.deleteMemoryInWorkspace(this.deps, id, scope.workspaceId, scope.agentId);
+        await crud.deleteMemory(this.deps, id, scope.userId);
+        return true;
+    }
+    /** Scope-dispatching list with agent visibility enforcement for workspace operations. */
+    async scopedList(scope, limit = 20, offset = 0, sourceSite, episodeId) {
+        if (scope.kind === 'workspace')
+            return crud.listMemoriesInWorkspace(this.deps, scope.workspaceId, limit, offset, scope.agentId);
+        return crud.listMemories(this.deps, scope.userId, limit, offset, sourceSite, episodeId);
+    }
+    // --- Search (legacy, prefer scopedSearch) ---
+    /** @deprecated Use scopedSearch instead. */
+    async search(userId, query, sourceSite, limit, asOf, referenceTime, namespaceScope, retrievalOptions) {
+        return performSearch(this.deps, userId, query, sourceSite, limit, asOf, referenceTime, namespaceScope, retrievalOptions);
+    }
+    /** @deprecated Use scopedSearch instead. */
+    async fastSearch(userId, query, sourceSite, limit, namespaceScope) {
+        return performFastSearch(this.deps, userId, query, sourceSite, limit, namespaceScope);
+    }
+    /** @deprecated Use scopedSearch instead. */
+    async workspaceSearch(userId, query, workspace, options = {}) {
+        return performWorkspaceSearch(this.deps, userId, query, workspace, options);
+    }
+    // --- CRUD ---
+    async list(userId, limit = 20, offset = 0, sourceSite, episodeId) { return crud.listMemories(this.deps, userId, limit, offset, sourceSite, episodeId); }
+    async get(id, userId) { return crud.getMemory(this.deps, id, userId); }
+    async expand(userId, memoryIds) { return crud.expandMemories(this.deps, userId, memoryIds); }
+    async delete(id, userId) { return crud.deleteMemory(this.deps, id, userId); }
+    async resetBySource(userId, sourceSite) { return crud.resetBySource(this.deps, userId, sourceSite); }
+    async getStats(userId) { return crud.getStats(this.deps, userId); }
+    // --- Consolidation / Lifecycle ---
+    async consolidate(userId) { return crud.consolidate(this.deps, userId); }
+    async executeConsolidation(userId) { return crud.performExecuteConsolidation(this.deps, userId); }
+    async reconcileDeferred(userId) { return crud.reconcileDeferred(this.deps, userId); }
+    async reconcileDeferredAll() { return crud.reconcileDeferredAll(this.deps); }
+    async getDeferredStatus(userId) { return crud.getDeferredStatus(this.deps, userId); }
+    async evaluateDecay(userId, referenceTime) { return crud.evaluateDecay(this.deps, userId, referenceTime); }
+    async archiveDecayed(userId, memoryIds) { return crud.archiveDecayed(this.deps, userId, memoryIds); }
+    async checkCap(userId) { return crud.checkCap(this.deps, userId); }
+    // --- Audit / Mutations ---
+    async getAuditTrail(userId, memoryId) { return crud.getAuditTrail(this.deps, userId, memoryId); }
+    async getMutationSummary(userId) { return crud.getMutationSummary(this.deps, userId); }
+    async getRecentMutations(userId, limit = 20) { return crud.getRecentMutations(this.deps, userId, limit); }
+    async backfillClaimSlots(userId) { return crud.backfillClaimSlots(this.deps, userId); }
+    async getReversalChain(userId, versionId) { return crud.getReversalChain(this.deps, userId, versionId); }
+    // --- Lessons ---
+    async getLessons(userId) { return crud.getLessons(this.deps, userId); }
+    async getLessonStats(userId) { return crud.getLessonStats(this.deps, userId); }
+    async reportLesson(userId, pattern, sourceMemoryIds, severity) { return crud.reportLesson(this.deps, userId, pattern, sourceMemoryIds, severity); }
+    async deactivateLesson(userId, lessonId) { return crud.deactivateLesson(this.deps, userId, lessonId); }
+    // --- First-mention events (chronological topic-introduction list) ---
+    /**
+     * Extract first-mention events from a conversation transcript and persist
+     * them to `first_mention_events`. Caller supplies the turn-id-to-memory-id
+     * mapping (the ingest pipeline does not retain turn structure, so the
+     * caller knows the mapping). Returns the parsed events. Best-effort: if
+     * the underlying LLM call fails or the service is not wired, returns `[]`
+     * without throwing.
+     */
+    async extractFirstMentions(userId, conversationText, sourceSite, memoryIdsByTurnId) {
+        const svc = this.deps.firstMentionService;
+        if (!svc)
+            return [];
+        return svc.extractAndStore(userId, conversationText, sourceSite, memoryIdsByTurnId);
+    }
+    // --- Event chains (TLL read API) ---
+    /**
+     * Retrieve per-entity chronological event chains from the Temporal Linkage
+     * List. Used by `GET /v1/memories/event-chains` and by EO-shaped read paths
+     * that need content alongside chain position. Returns one entry per entity
+     * with an ordered list of events (memoryId, content, observationDate,
+     * positionInChain). Entities without events are dropped from the result.
+     */
+    async getEventChains(userId, entityIds) {
+        const tll = this.deps.tllRepository;
+        if (!tll)
+            return [];
+        return tll.chainEventsForEntities(userId, entityIds);
+    }
+}

package/dist/services/memory-storage.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Canonical fact storage, projection writing, entity linking, and claim slot resolution.
+ * These helpers are used by both the ingest pipeline and the AUDN decision executor.
+ */
+import { type ClaimSlotInput } from '../db/claim-repository.js';
+import { type ExtractedEntity } from './extraction.js';
+import { type CandidateMemory } from './conflict-policy.js';
+import { type TemporalStateClassification } from './temporal-state-write.js';
+import type { AudnFactContext, ClaimTarget, FactInput, MemoryServiceDeps, Outcome } from './memory-service-types.js';
+interface StoreProjectionOptions {
+    cmoId?: string;
+    logicalTimestamp?: Date;
+    workspace?: import('../db/repository-types.js').WorkspaceContext;
+    /** BEAM v38: temporal-state classification to land on the new row. */
+    temporal?: TemporalStateClassification | null;
+}
+/** Store a new canonical fact: CMO, projection, claim, evidence, entities. */
+export declare function storeCanonicalFact(deps: MemoryServiceDeps, ctx: AudnFactContext): Promise<{
+    outcome: Outcome;
+    memoryId: string | null;
+}>;
+export declare function storeProjection(deps: MemoryServiceDeps, userId: string, fact: FactInput, embedding: number[], sourceSite: string, sourceUrl: string, episodeId: string, trustScore: number, options?: StoreProjectionOptions): Promise<string | null>;
+export declare function resolveDeterministicClaimSlot(deps: MemoryServiceDeps, userId: string, fact: FactInput): Promise<ClaimSlotInput | null>;
+/**
+ * Entity-scoped dedup: if AUDN proposed UPDATE or NOOP targeting a memory
+ * that shares no entities with the new fact, promote to ADD.
+ */
+export declare function applyEntityScopedDedup(deps: MemoryServiceDeps, decision: import('./extraction.js').AUDNDecision, userId: string, factEntities: ExtractedEntity[]): Promise<import('./extraction.js').AUDNDecision>;
+/** Ensure a claim target exists for the given memory, creating one if needed. */
+export declare function ensureClaimTarget(deps: MemoryServiceDeps, userId: string, memoryId: string): Promise<ClaimTarget>;
+export declare function findConflictCandidates(deps: MemoryServiceDeps, userId: string, factText: string, embedding: number[]): Promise<CandidateMemory[]>;
+export declare function findSlotConflictCandidates(deps: MemoryServiceDeps, userId: string, claimSlot: ClaimSlotInput | null): Promise<CandidateMemory[]>;
+export {};

package/dist/services/memory-storage.js

@@ -0,0 +1,328 @@
+/**
+ * Canonical fact storage, projection writing, entity linking, and claim slot resolution.
+ * These helpers are used by both the ingest pipeline and the AUDN decision executor.
+ */
+import { embedTexts } from './embedding.js';
+import { classifyNetwork } from './memory-network.js';
+import { buildRelationClaimSlot } from './claim-slotting.js';
+import { extractConflictKeywords, mergeCandidates } from './conflict-policy.js';
+import { buildAtomicFactProjection, buildForesightProjections } from './memcell-projection.js';
+import { inferNamespace, classifyNamespace } from './namespace-retrieval.js';
+import { generateL1Overview } from './tiered-context.js';
+import { emitAuditEvent } from './audit-events.js';
+import { derivePersistedClaimSlot } from './memory-crud.js';
+import { emitLineageEvent } from './memory-lineage.js';
+import { classifyTemporalStateForWrite, supersedeAfterStore, } from './temporal-state-write.js';
+/** Store a new canonical fact: CMO, projection, claim, evidence, entities. */
+export async function storeCanonicalFact(deps, ctx) {
+    const { userId, fact, embedding, sourceSite, sourceUrl, episodeId, trustScore, claimSlot, logicalTimestamp, workspace } = ctx;
+    // BEAM v38: classify temporal state BEFORE storing so we can land
+    // `state_key` / `event_start` on the new row's first INSERT. Fails closed.
+    const temporal = await maybeClassifyTemporalForFact(deps, ctx);
+    const lineage = await emitLineageEvent({ claims: deps.stores.claim, repo: deps.stores.memory, config: deps.config }, {
+        kind: 'canonical-add',
+        userId,
+        fact,
+        embedding,
+        sourceSite,
+        sourceUrl,
+        episodeId,
+        logicalTimestamp,
+        claimSlot: claimSlot ?? null,
+        createProjection: async (cmoId) => storeProjection(deps, userId, fact, embedding, sourceSite, sourceUrl, episodeId, trustScore, {
+            cmoId,
+            logicalTimestamp,
+            workspace,
+            temporal,
+        }),
+    });
+    if (!lineage?.memoryId)
+        return { outcome: 'skipped', memoryId: null };
+    const memoryId = lineage.memoryId;
+    // BEAM v38: close prior memory windows for this state_key. Fails closed.
+    if (temporal) {
+        await supersedeAfterStore({
+            pool: deps.stores.pool,
+            userId,
+            stateKey: temporal.stateKey,
+            newMemoryId: memoryId,
+            eventStart: temporal.eventStart,
+        });
+    }
+    if (deps.config.entityGraphEnabled && deps.stores.entity) {
+        await resolveAndLinkEntities(deps, userId, memoryId, fact.entities, fact.relations, embedding, logicalTimestamp);
+        if (!claimSlot) {
+            const persistedSlot = await derivePersistedClaimSlot(deps, userId, memoryId);
+            if (persistedSlot) {
+                await deps.stores.claim.updateClaimSlot(userId, lineage.claimId, persistedSlot);
+            }
+        }
+    }
+    if (deps.observationService && fact.entities.length > 0) {
+        const subjects = fact.entities.map((e) => e.name);
+        deps.observationService.markDirty(userId, subjects).catch((err) => console.error('[observation] markDirty failed:', err));
+    }
+    return { outcome: 'stored', memoryId };
+}
+/**
+ * BEAM v38: run the temporal-state classifier when the flag is on.
+ * Returns null when the flag is off, when the memory is non-stateful,
+ * or when the classifier rejects the LLM output. Re-throws on LLM
+ * transport errors so the ingest fails closed.
+ */
+async function maybeClassifyTemporalForFact(deps, ctx) {
+    if (!deps.config.temporalStateEnabled)
+        return null;
+    const observedAt = ctx.logicalTimestamp ?? new Date();
+    return classifyTemporalStateForWrite({
+        userId: ctx.userId,
+        memoryText: ctx.fact.fact,
+        observedAt,
+        model: deps.config.llmModel,
+    });
+}
+export async function storeProjection(deps, userId, fact, embedding, sourceSite, sourceUrl, episodeId, trustScore, options = {}) {
+    const namespace = deps.config.namespaceClassificationEnabled
+        ? await classifyNamespace(fact.fact, sourceSite, fact.keywords)
+        : inferNamespace(fact.fact, sourceSite, fact.keywords);
+    const overview = generateL1Overview(fact.fact);
+    const network = fact.network ?? classifyNetwork(fact).network;
+    const memoryId = await deps.stores.memory.storeMemory({
+        userId, content: fact.fact, embedding,
+        memoryType: fact.type === 'knowledge' ? 'semantic' : 'episodic',
+        importance: fact.importance, sourceSite, sourceUrl, episodeId,
+        metadata: options.cmoId ? { cmo_id: options.cmoId } : undefined,
+        keywords: fact.keywords.join(' '),
+        namespace: namespace ?? undefined,
+        summary: fact.headline,
+        overview: overview !== fact.fact ? overview : '',
+        trustScore, network,
+        opinionConfidence: fact.opinionConfidence ?? null,
+        workspaceId: options.workspace?.workspaceId,
+        agentId: options.workspace?.agentId,
+        visibility: options.workspace?.visibility,
+        createdAt: options.logicalTimestamp,
+        observedAt: options.logicalTimestamp,
+        stateKey: options.temporal?.stateKey,
+        eventStart: options.temporal?.eventStart,
+        eventEnd: options.temporal?.eventEnd ?? null,
+    });
+    const atomicFact = buildAtomicFactProjection(fact, embedding);
+    await deps.stores.representation.storeAtomicFacts([{
+            userId, parentMemoryId: memoryId,
+            factText: atomicFact.factText, embedding: atomicFact.embedding,
+            factType: atomicFact.factType, importance: atomicFact.importance,
+            sourceSite, sourceUrl, episodeId,
+            keywords: atomicFact.keywords.join(' '), metadata: atomicFact.metadata,
+            workspaceId: options.workspace?.workspaceId, agentId: options.workspace?.agentId,
+        }]);
+    const foresight = buildForesightProjections(fact, embedding);
+    if (foresight.length > 0) {
+        await deps.stores.representation.storeForesight(foresight.map((entry) => ({
+            userId, parentMemoryId: memoryId,
+            content: entry.content, embedding: entry.embedding, foresightType: entry.foresightType,
+            sourceSite, sourceUrl, episodeId,
+            metadata: entry.metadata, validFrom: entry.validFrom, validTo: entry.validTo,
+            workspaceId: options.workspace?.workspaceId, agentId: options.workspace?.agentId,
+        })));
+    }
+    if (deps.config.auditLoggingEnabled) {
+        emitAuditEvent('memory:ingest', userId, {
+            factType: fact.type, importance: fact.importance, trustScore,
+        }, { memoryId, sourceSite });
+    }
+    return memoryId;
+}
+export async function resolveDeterministicClaimSlot(deps, userId, fact) {
+    if (!deps.stores.entity || fact.entities.length === 0 || fact.relations.length === 0) {
+        return null;
+    }
+    const canonicalEntries = await Promise.all(fact.entities.map(async (entity) => {
+        const match = await deps.stores.entity.findDeterministicEntity(userId, entity.type, entity.name);
+        if (!match)
+            return null;
+        return [
+            entity.name.toLowerCase(),
+            {
+                extractedName: entity.name,
+                entityId: match.id,
+                canonicalName: match.name,
+                entityType: match.entity_type,
+            },
+        ];
+    }));
+    const canonicalMap = new Map(canonicalEntries.filter((entry) => entry !== null));
+    return buildRelationClaimSlot(fact.relations, canonicalMap);
+}
+/**
+ * Entity-scoped dedup: if AUDN proposed UPDATE or NOOP targeting a memory
+ * that shares no entities with the new fact, promote to ADD.
+ */
+export async function applyEntityScopedDedup(deps, decision, userId, factEntities) {
+    if (decision.action !== 'UPDATE' && decision.action !== 'NOOP')
+        return decision;
+    if (!decision.targetMemoryId || !deps.stores.entity || factEntities.length === 0)
+        return decision;
+    const existingEntities = await deps.stores.entity.getEntitiesForMemory(decision.targetMemoryId);
+    if (existingEntities.length === 0)
+        return decision;
+    const factEntityNames = new Set(factEntities.map((e) => e.name.toLowerCase()));
+    const hasSharedEntity = existingEntities.some((e) => factEntityNames.has(e.name.toLowerCase()) ||
+        e.alias_names.some((a) => factEntityNames.has(a.toLowerCase())));
+    if (!hasSharedEntity) {
+        return { ...decision, action: 'ADD', targetMemoryId: null, updatedContent: null };
+    }
+    return decision;
+}
+/**
+ * Resolve extracted entities (dedup by embedding + type), link them to the
+ * memory, then store any extracted relations between entities.
+ */
+async function resolveAndLinkEntities(deps, userId, memoryId, entities, relations, factEmbedding, logicalTimestamp) {
+    if (!deps.stores.entity || entities.length === 0)
+        return;
+    const entityEmbeddings = await embedTexts(entities.map((e) => e.name));
+    const nameToEntityId = await resolveEntities(deps, userId, memoryId, entities, entityEmbeddings);
+    await storeRelations(deps, userId, memoryId, relations, nameToEntityId);
+    await maybeAppendTll(deps, userId, memoryId, nameToEntityId, logicalTimestamp);
+}
+/**
+ * Phase 4 — TLL append: per-entity event-chain extension. Each new memory
+ * referencing an entity becomes the new tip of that entity's chain. Used at
+ * retrieval-time for EO/MSR/TR queries. Best-effort, fire-and-forget to
+ * keep ingest hot path fast.
+ *
+ * The chain orders by observation_date ASC, so we use the memory's
+ * observed_at (the conversation timestamp) instead of new Date() (the
+ * ingest-arrival timestamp). Otherwise out-of-order or backfilled
+ * conversations would chain by ingest time, breaking event ordering.
+ */
+async function maybeAppendTll(deps, userId, memoryId, nameToEntityId, logicalTimestamp) {
+    if (!deps.tllRepository)
+        return;
+    const entityIds = [...nameToEntityId.values()];
+    if (entityIds.length === 0)
+        return;
+    const observationDate = await resolveTllObservationDate(deps, userId, memoryId, logicalTimestamp);
+    // Fire-and-forget: TLL append is best-effort augmentation of the
+    // ingest hot path. A failure here should NOT block ingest, which is
+    // why we deliberately drop the promise. The `[tll-append-failed]`
+    // structured prefix is what observability tooling greps for; pair
+    // with `tll_expansion_failed` on the read path.
+    deps.tllRepository
+        .append(userId, memoryId, entityIds, observationDate)
+        .catch((err) => console.error('[tll-append-failed]', err instanceof Error ? err.message : String(err)));
+}
+/**
+ * Resolve the observation_date used for TLL chain ordering. Prefers the
+ * caller-supplied logical timestamp (the canonical conversation time);
+ * falls back to the memory row's observed_at column when the caller didn't
+ * supply one. Last-resort fallback to new Date() only fires if the row
+ * lookup fails — never silently drop the append.
+ */
+async function resolveTllObservationDate(deps, userId, memoryId, logicalTimestamp) {
+    if (logicalTimestamp)
+        return logicalTimestamp;
+    try {
+        const memory = await deps.stores.memory.getMemory(memoryId, userId);
+        if (memory?.observed_at)
+            return memory.observed_at;
+    }
+    catch (err) {
+        console.error('[tll] failed to resolve observed_at:', err instanceof Error ? err.message : err);
+    }
+    return new Date();
+}
+/** Resolve each extracted entity and link it to the memory. */
+async function resolveEntities(deps, userId, memoryId, entities, entityEmbeddings) {
+    const nameToEntityId = new Map();
+    for (let i = 0; i < entities.length; i++) {
+        try {
+            const entityId = await deps.stores.entity.resolveEntity({
+                userId,
+                name: entities[i].name,
+                entityType: entities[i].type,
+                embedding: entityEmbeddings[i],
+            });
+            await deps.stores.entity.linkMemoryToEntity(memoryId, entityId);
+            nameToEntityId.set(entities[i].name.toLowerCase(), entityId);
+        }
+        catch (err) {
+            console.error(`Entity resolution failed for "${entities[i].name}": ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    return nameToEntityId;
+}
+/** Store extracted relations between resolved entities. */
+async function storeRelations(deps, userId, memoryId, relations, nameToEntityId) {
+    for (const relation of relations) {
+        const sourceId = nameToEntityId.get(relation.source.toLowerCase());
+        const targetId = nameToEntityId.get(relation.target.toLowerCase());
+        if (!sourceId || !targetId || sourceId === targetId)
+            continue;
+        try {
+            await deps.stores.entity.upsertRelation({
+                userId,
+                sourceEntityId: sourceId,
+                targetEntityId: targetId,
+                relationType: relation.type,
+                sourceMemoryId: memoryId,
+            });
+        }
+        catch (err) {
+            console.error(`Relation storage failed for "${relation.source}" -> "${relation.target}": ${err instanceof Error ? err.message : err}`);
+        }
+    }
+}
+/** Ensure a claim target exists for the given memory, creating one if needed. */
+export async function ensureClaimTarget(deps, userId, memoryId) {
+    const memory = await deps.stores.memory.getMemoryIncludingDeleted(memoryId, userId);
+    if (!memory)
+        throw new Error(`Target memory not found: ${memoryId}`);
+    const cmoId = typeof memory.metadata.cmo_id === 'string' ? memory.metadata.cmo_id : null;
+    const version = await deps.stores.claim.getClaimVersionByMemoryId(userId, memoryId);
+    if (version)
+        return { claimId: version.claim_id, versionId: version.id, memoryId, cmoId };
+    const lineage = await emitLineageEvent({ claims: deps.stores.claim, config: deps.config }, {
+        kind: 'claim-backfill',
+        userId,
+        memory: {
+            id: memory.id,
+            content: memory.content,
+            embedding: memory.embedding,
+            importance: memory.importance,
+            sourceSite: memory.source_site,
+            sourceUrl: memory.source_url,
+            episodeId: memory.episode_id ?? undefined,
+            createdAt: memory.created_at,
+            memoryType: memory.memory_type,
+            cmoId,
+        },
+    });
+    if (!lineage)
+        throw new Error(`Claim backfill unexpectedly skipped for memory: ${memory.id}`);
+    return { claimId: lineage.claimId, versionId: lineage.versionId, memoryId: memory.id, cmoId };
+}
+export async function findConflictCandidates(deps, userId, factText, embedding) {
+    const [vectorCandidates, keywordCandidates] = await Promise.all([
+        deps.stores.search.findNearDuplicates(userId, embedding, deps.config.audnCandidateThreshold),
+        deps.stores.search.findKeywordCandidates(userId, extractConflictKeywords(factText)),
+    ]);
+    return mergeCandidates(vectorCandidates, keywordCandidates);
+}
+export async function findSlotConflictCandidates(deps, userId, claimSlot) {
+    if (!claimSlot)
+        return [];
+    const target = await deps.stores.claim.getActiveClaimTargetBySlot(userId, claimSlot.slotKey);
+    if (!target)
+        return [];
+    const memory = await deps.stores.memory.getMemory(target.memoryId, userId);
+    if (!memory)
+        return [];
+    return [{
+            id: memory.id,
+            content: memory.content,
+            similarity: 1,
+            importance: memory.importance,
+        }];
+}

package/dist/services/msr-aggregator.d.ts

@@ -0,0 +1,38 @@
+/**
+ * MSR cross-conversation aggregator.
+ *
+ * Retrieval-side intervention for multi-session-reasoning queries. v39-multihop
+ * diagnostic on v26 MSR failures: gold facts WERE in the top-K but spread
+ * across 2-4 conversations; the answer LLM could not synthesize them and
+ * returned inflated counts ("Twenty-three" vs gold "Four").
+ *
+ * Strategy: group retrieved memories by `episode_id` (= conversation id in
+ * BEAM). For each group with >=2 memories, emit a 1-sentence summary via the
+ * configured chat LLM (cheap — defaults to Haiku). Groups with a single
+ * memory pass through verbatim (no LLM call). The concatenated
+ * `## CONVERSATION N SUMMARY` blocks become an additional channel BEFORE
+ * the standard OBSERVATIONS / TIMELINE / ENTITY_STATE blocks.
+ *
+ * Fail-closed: any LLM error during summarization throws — no silent
+ * fallback to raw text. Matches the AUDN mutation invariant.
+ */
+import type { SearchResult } from '../db/memory-repository.js';
+import type { LLMProvider } from './llm.js';
+/** Caller-supplied dependencies. Decoupled from MemoryServiceDeps for testability. */
+export interface MsrAggregatorDeps {
+    /** Chat LLM provider — shared singleton in production, mocked in tests. */
+    llm: LLMProvider;
+    /** Model used for per-conversation summary calls. Default Haiku-cheap. */
+    model: string;
+    /** Optional override for the per-summary token budget. Default 80. */
+    maxTokensPerSummary?: number;
+}
+/**
+ * Build the per-conversation aggregated string. Groups are 1-indexed by
+ * first-seen episode order. Multi-memory groups go through the LLM; single-
+ * memory groups pass through verbatim.
+ *
+ * Returns an empty string when there are no retrieved memories — caller
+ * should treat that as "no MSR channel to add" and skip the prefix.
+ */
+export declare function aggregateByConversation(memories: ReadonlyArray<SearchResult>, query: string, deps: MsrAggregatorDeps): Promise<string>;