@atomicmemory/core 1.0.0

package/dist/services/memory-audn.js

@@ -0,0 +1,419 @@
+/**
+ * AUDN (Add/Update/Delete/Noop) decision resolution and mutation execution.
+ * Handles fast-path AUDN, deferred AUDN, conflict candidate discovery,
+ * and the full mutation pipeline (update, supersede, delete canonical facts).
+ */
+import { embedText } from './embedding.js';
+import { cachedResolveAUDN } from './extraction-cache.js';
+import { applyOpinionSignal, audnActionToOpinionSignal } from './memory-network.js';
+import { buildAtomicFactProjection, buildForesightProjections } from './memcell-projection.js';
+import { applyClarificationOverrides, mergeCandidates } from './conflict-policy.js';
+import { emitAuditEvent } from './audit-events.js';
+import { recordContradictionLesson } from './lesson-service.js';
+import { shouldDeferAudn, deferMemoryForReconciliation } from './deferred-audn.js';
+import { timed } from './timing.js';
+import { emitLineageEvent } from './memory-lineage.js';
+import { storeCanonicalFact, storeProjection, applyEntityScopedDedup, ensureClaimTarget, findConflictCandidates, findSlotConflictCandidates } from './memory-storage.js';
+/** Find conflict candidates, merge slot-aware candidates, and filter out superseded. */
+export async function findFilteredCandidates(deps, userId, fact, embedding, claimSlot, supersededTargets) {
+    const candidates = await timed('ingest.fact.find-conflicts', () => findConflictCandidates(deps, userId, fact.fact, embedding));
+    const slotAwareCandidates = claimSlot
+        ? await timed('ingest.fact.find-slot-candidates', () => findSlotConflictCandidates(deps, userId, claimSlot))
+        : [];
+    const merged = mergeCandidates(candidates, slotAwareCandidates);
+    return merged.filter((c) => !supersededTargets.has(c.id));
+}
+/** Resolve AUDN decision (fast/deferred/full) and execute it. */
+export async function resolveAndExecuteAudn(deps, userId, fact, embedding, sourceSite, sourceUrl, episodeId, trustScore, claimSlot, logicalTimestamp, filteredCandidates, supersededTargets, workspace, traceContext) {
+    const candidateIds = new Set(filteredCandidates.map((c) => c.id));
+    const ctx = { userId, fact, embedding, sourceSite, sourceUrl, episodeId, trustScore, claimSlot, logicalTimestamp, workspace };
+    const fastDecision = tryFastAUDN(fact.fact, filteredCandidates, deps.config);
+    if (fastDecision) {
+        return executeAndTrackSupersede(deps, fastDecision, candidateIds, ctx, supersededTargets, requireTraceContext(traceContext), 'fast-audn', 'NOOP', fastDecision.action);
+    }
+    if (shouldDeferAudn(false, filteredCandidates.length)) {
+        const result = await storeCanonicalFact(deps, ctx);
+        if (result.memoryId) {
+            await deferMemoryForReconciliation(deps.stores.pool, result.memoryId, filteredCandidates);
+            console.log(`[deferred-audn] Deferred: ${result.memoryId} (${filteredCandidates.length} candidates)`);
+        }
+        return {
+            ...result,
+            embedding,
+            trace: buildAudnTrace(requireTraceContext(traceContext), 'deferred-audn', 'ADD', 'deferred-audn-store', result.outcome, result.memoryId, null),
+        };
+    }
+    if (deps.config.tbcEnabled) {
+        const { resolveAndExecuteTbc } = await import('./tbc-execution.js');
+        return resolveAndExecuteTbc(deps, ctx, filteredCandidates, candidateIds, supersededTargets, requireTraceContext(traceContext));
+    }
+    const rawDecision = await timed('ingest.fact.audn', () => cachedResolveAUDN(fact.fact, filteredCandidates));
+    let decision = applyClarificationOverrides(rawDecision, fact.fact, filteredCandidates, fact.keywords, fact.type);
+    if (deps.config.entityGraphEnabled && deps.stores.entity) {
+        decision = await applyEntityScopedDedup(deps, decision, userId, fact.entities);
+    }
+    return executeAndTrackSupersede(deps, decision, candidateIds, ctx, supersededTargets, requireTraceContext(traceContext), 'llm-audn', rawDecision.action, decision.action);
+}
+/** Execute the AUDN decision and track supersede targets. */
+async function executeAndTrackSupersede(deps, decision, candidateIds, ctx, supersededTargets, traceContext, source, rawAction, effectiveAction) {
+    const result = await executeAudnDecision(deps, decision, candidateIds, ctx);
+    if (decision.action === 'SUPERSEDE' && result.memoryId) {
+        supersededTargets.add(result.memoryId);
+    }
+    return {
+        ...result,
+        embedding: ctx.embedding,
+        trace: buildAudnTrace(traceContext, source, effectiveAction, reasonCodeForDecision(source, decision, result), result.outcome, result.memoryId, decision.targetMemoryId, rawAction),
+    };
+}
+/**
+ * Execute an AUDN decision via the standard ingest seam.
+ *
+ * Exposed (renamed from the legacy private `executeDecision`) so that the
+ * TBC executor in `tbc-execution.ts` can route Affirm/Update/Retract/
+ * Supersede through the same mutation path AUDN uses today, keeping the
+ * fail-closed semantics in place.
+ */
+export async function executeAudnDecision(deps, decision, candidateIds, ctx) {
+    const opinionResult = await tryOpinionIntercept(deps, decision, ctx);
+    if (opinionResult)
+        return opinionResult;
+    if (decision.action === 'ADD') {
+        return storeCanonicalFact(deps, ctx);
+    }
+    if (decision.action === 'NOOP') {
+        return recordNoop(deps, decision.targetMemoryId, candidateIds, ctx.userId, ctx.episodeId, ctx.fact.fact);
+    }
+    if (decision.action === 'CLARIFY') {
+        return storeClarification(deps, decision, ctx);
+    }
+    if (!decision.targetMemoryId || !candidateIds.has(decision.targetMemoryId)) {
+        console.error(`AUDN ${decision.action} rejected for fact "${ctx.fact.fact.slice(0, 50)}...": invalid targetMemoryId "${decision.targetMemoryId}". Candidates were: ${[...candidateIds].join(', ')}`);
+        return storeCanonicalFact(deps, ctx);
+    }
+    return executeMutationDecision(deps, decision, ctx);
+}
+function buildAudnTrace(traceContext, source, action, reasonCode, outcome, memoryId, targetMemoryId, rawAction) {
+    return {
+        factText: traceContext.fact.fact,
+        headline: traceContext.fact.headline,
+        factType: traceContext.fact.type,
+        importance: traceContext.fact.importance,
+        ...(traceContext.logicalTimestamp ? { logicalTimestamp: traceContext.logicalTimestamp.toISOString() } : {}),
+        writeSecurity: {
+            allowed: traceContext.writeSecurity.allowed,
+            blockedBy: traceContext.writeSecurity.blockedBy,
+            trustScore: traceContext.writeSecurity.trust.score,
+        },
+        ...(traceContext.entropyResult ? { entropyGate: traceContext.entropyResult } : {}),
+        candidates: traceContext.candidates,
+        decision: {
+            source,
+            action,
+            reasonCode,
+            targetMemoryId,
+            candidateIds: traceContext.candidates.map((candidate) => candidate.id),
+            ...(rawAction ? { rawAction } : {}),
+        },
+        outcome,
+        memoryId,
+    };
+}
+function requireTraceContext(traceContext) {
+    if (!traceContext) {
+        throw new Error('resolveAndExecuteAudn requires traceContext.');
+    }
+    return traceContext;
+}
+function reasonCodeForDecision(source, decision, result) {
+    if (source === 'fast-audn')
+        return 'fast-audn-noop';
+    // BEAM CR fix: bilateral preservation intercepted DELETE/SUPERSEDE.
+    if (result.outcome === 'preserved_contradiction')
+        return 'llm-audn-bilateral-preserve';
+    if (isInvalidTargetFallback(decision, result)) {
+        return 'invalid-target-fallback';
+    }
+    return decision.action === 'SUPERSEDE' && !result.memoryId
+        ? 'invalid-target-fallback'
+        : decisionReasonCode(decision.action);
+}
+function isInvalidTargetFallback(decision, result) {
+    // The bilateral path emits outcome='preserved_contradiction' for DELETE
+    // and SUPERSEDE — that is the intended behavior, not a stored-fallback.
+    if (result.outcome === 'preserved_contradiction')
+        return false;
+    return !['ADD', 'NOOP', 'CLARIFY'].includes(decision.action) && result.outcome === 'stored';
+}
+function decisionReasonCode(action) {
+    const reasonCodes = {
+        ADD: 'llm-audn-add',
+        NOOP: 'llm-audn-noop',
+        CLARIFY: 'llm-audn-clarify',
+        UPDATE: 'llm-audn-update',
+        DELETE: 'llm-audn-delete',
+        SUPERSEDE: 'llm-audn-supersede',
+    };
+    return reasonCodes[action];
+}
+/** Handle opinion network intercept: update confidence instead of normal AUDN. */
+async function tryOpinionIntercept(deps, decision, ctx) {
+    if (ctx.fact.network !== 'opinion' || !decision.targetMemoryId || decision.action === 'ADD')
+        return null;
+    const targetMemory = await deps.stores.memory.getMemory(decision.targetMemoryId, ctx.userId);
+    if (!targetMemory || targetMemory.network !== 'opinion' || targetMemory.opinion_confidence === null)
+        return null;
+    const signal = audnActionToOpinionSignal(decision.action);
+    const newConfidence = applyOpinionSignal(targetMemory.opinion_confidence, signal);
+    await deps.stores.memory.updateOpinionConfidence(ctx.userId, decision.targetMemoryId, newConfidence);
+    if (newConfidence <= 0 && targetMemory.opinion_confidence > 0) {
+        await deps.stores.memory.storeMemory({
+            userId: ctx.userId, content: ctx.fact.fact, embedding: ctx.embedding, memoryType: 'episodic', importance: ctx.fact.importance,
+            sourceSite: ctx.sourceSite, sourceUrl: ctx.sourceUrl, episodeId: ctx.episodeId, status: 'needs_clarification',
+            metadata: { clarification_note: 'Opinion confidence dropped to zero', target_memory_id: decision.targetMemoryId },
+            trustScore: ctx.trustScore, network: 'opinion', opinionConfidence: 0,
+            createdAt: ctx.logicalTimestamp, observedAt: ctx.logicalTimestamp,
+            workspaceId: ctx.workspace?.workspaceId, agentId: ctx.workspace?.agentId, visibility: ctx.workspace?.visibility,
+        });
+    }
+    if (decision.action === 'SUPERSEDE') {
+        return storeCanonicalFact(deps, ctx);
+    }
+    return { outcome: decision.action === 'NOOP' ? 'skipped' : 'updated', memoryId: decision.targetMemoryId };
+}
+/** Store a fact as needs_clarification for the CLARIFY action. */
+async function storeClarification(deps, decision, ctx) {
+    await deps.stores.memory.storeMemory({
+        userId: ctx.userId, content: ctx.fact.fact, embedding: ctx.embedding,
+        memoryType: ctx.fact.type === 'knowledge' ? 'semantic' : 'episodic',
+        importance: ctx.fact.importance, sourceSite: ctx.sourceSite, sourceUrl: ctx.sourceUrl, episodeId: ctx.episodeId,
+        status: 'needs_clarification',
+        metadata: {
+            clarification_note: decision.clarificationNote ?? 'Low-confidence contradiction detected',
+            target_memory_id: decision.targetMemoryId ?? undefined,
+            contradiction_confidence: decision.contradictionConfidence ?? undefined,
+        },
+        trustScore: ctx.trustScore, createdAt: ctx.logicalTimestamp, observedAt: ctx.logicalTimestamp,
+        workspaceId: ctx.workspace?.workspaceId, agentId: ctx.workspace?.agentId, visibility: ctx.workspace?.visibility,
+    });
+    return { outcome: 'skipped', memoryId: null };
+}
+/** Execute UPDATE, DELETE, or SUPERSEDE — fails closed on error. */
+async function executeMutationDecision(deps, decision, ctx) {
+    if (decision.action === 'UPDATE') {
+        return await updateCanonicalFact(deps, decision, ctx);
+    }
+    // BEAM CR fix: bilateral preservation intercepts DELETE/SUPERSEDE when the
+    // flag is on and the contradictions store is wired. Keeps both memories
+    // instead of discarding the older side. Fails closed: any error bubbles
+    // up instead of silently falling back to ADD.
+    if ((decision.action === 'DELETE' || decision.action === 'SUPERSEDE') &&
+        deps.config.contradictionPreservationEnabled &&
+        deps.stores.contradictions) {
+        return await preserveBilateralContradiction(deps, decision, ctx);
+    }
+    if (decision.action === 'DELETE') {
+        return await deleteCanonicalFact(deps, decision.targetMemoryId, ctx.userId, ctx.fact, ctx.sourceSite, ctx.sourceUrl, ctx.episodeId, decision.contradictionConfidence, ctx.logicalTimestamp);
+    }
+    return await supersedeCanonicalFact(deps, decision.targetMemoryId, ctx.userId, ctx.fact, ctx.embedding, ctx.sourceSite, ctx.sourceUrl, ctx.episodeId, decision.contradictionConfidence, ctx.trustScore, ctx.logicalTimestamp, ctx.workspace);
+}
+/**
+ * BEAM CR fix — bilateral preservation path. Instead of expiring/soft-deleting
+ * the prior memory, store the new fact as a standalone canonical row, then
+ * mark BOTH rows as contradicting each other. Records the pair in
+ * `memory_contradictions` so retrieval and analytics can surface both sides.
+ * Fails closed: errors propagate to the caller so AUDN never silently falls
+ * back to ADD (per CLAUDE.md mandate).
+ */
+async function preserveBilateralContradiction(deps, decision, ctx) {
+    const contradictions = deps.stores.contradictions;
+    if (!contradictions) {
+        throw new Error('AUDN bilateral preservation: contradictions store missing.');
+    }
+    const targetMemoryId = decision.targetMemoryId;
+    if (!targetMemoryId) {
+        throw new Error('AUDN bilateral preservation: missing targetMemoryId.');
+    }
+    const existing = await deps.stores.memory.getMemoryIncludingDeleted(targetMemoryId, ctx.userId);
+    if (!existing) {
+        throw new Error(`AUDN bilateral preservation: target memory ${targetMemoryId} not found.`);
+    }
+    const newMemoryId = await storeProjection(deps, ctx.userId, ctx.fact, ctx.embedding, ctx.sourceSite, ctx.sourceUrl, ctx.episodeId, ctx.trustScore, { logicalTimestamp: ctx.logicalTimestamp, workspace: ctx.workspace });
+    if (!newMemoryId) {
+        throw new Error(`AUDN bilateral preservation: storeProjection returned no id for target ${targetMemoryId}.`);
+    }
+    await contradictions.record({
+        userId: ctx.userId,
+        conversationId: ctx.episodeId,
+        leftMemoryId: existing.id,
+        rightMemoryId: newMemoryId,
+        leftSummary: existing.content,
+        rightSummary: ctx.fact.fact,
+    });
+    await contradictions.markContradictionFlagsBilateral(ctx.userId, existing.id, newMemoryId);
+    if (deps.config.auditLoggingEnabled) {
+        emitAuditEvent('memory:contradiction-preserved', ctx.userId, {
+            action: decision.action,
+            leftMemoryId: existing.id,
+            rightMemoryId: newMemoryId,
+            contradictionConfidence: decision.contradictionConfidence,
+        }, { memoryId: newMemoryId });
+    }
+    return { outcome: 'preserved_contradiction', memoryId: newMemoryId };
+}
+async function updateCanonicalFact(deps, decision, ctx) {
+    const { userId, fact, sourceSite, sourceUrl, episodeId, trustScore, logicalTimestamp, workspace } = ctx;
+    if (!decision.updatedContent) {
+        throw new Error(`AUDN UPDATE failed: missing updatedContent for target "${decision.targetMemoryId}"`);
+    }
+    const target = await ensureClaimTarget(deps, userId, decision.targetMemoryId);
+    const updatedEmbedding = await embedText(decision.updatedContent);
+    await deps.stores.memory.updateMemoryContent(userId, target.memoryId, decision.updatedContent, updatedEmbedding, fact.importance, fact.keywords.join(' '), trustScore);
+    const updatedAtomicFact = buildAtomicFactProjection({ ...fact, fact: decision.updatedContent }, updatedEmbedding);
+    await deps.stores.representation.replaceAtomicFactsForMemory(userId, target.memoryId, [{
+            userId, parentMemoryId: target.memoryId,
+            factText: updatedAtomicFact.factText, embedding: updatedAtomicFact.embedding,
+            factType: updatedAtomicFact.factType, importance: updatedAtomicFact.importance,
+            sourceSite, sourceUrl, episodeId,
+            keywords: updatedAtomicFact.keywords.join(' '), metadata: updatedAtomicFact.metadata,
+            workspaceId: workspace?.workspaceId, agentId: workspace?.agentId,
+        }]);
+    const updatedForesight = buildForesightProjections({ ...fact, fact: decision.updatedContent }, updatedEmbedding);
+    await deps.stores.representation.replaceForesightForMemory(userId, target.memoryId, updatedForesight.map((entry) => ({
+        userId, parentMemoryId: target.memoryId,
+        content: entry.content, embedding: entry.embedding, foresightType: entry.foresightType,
+        sourceSite, sourceUrl, episodeId,
+        metadata: entry.metadata, validFrom: entry.validFrom, validTo: entry.validTo,
+        workspaceId: workspace?.workspaceId, agentId: workspace?.agentId,
+    })));
+    const lineage = await emitLineageEvent({ claims: deps.stores.claim, repo: deps.stores.memory, config: deps.config }, {
+        kind: 'canonical-update',
+        userId,
+        fact,
+        updatedContent: decision.updatedContent,
+        updatedEmbedding,
+        sourceSite,
+        sourceUrl,
+        episodeId,
+        logicalTimestamp,
+        target,
+        contradictionConfidence: decision.contradictionConfidence,
+    });
+    if (!lineage?.cmoId) {
+        throw new Error(`AUDN UPDATE failed: missing successor canonical object for "${target.memoryId}"`);
+    }
+    await deps.stores.memory.updateMemoryMetadata(userId, target.memoryId, { cmo_id: lineage.cmoId });
+    return { outcome: 'updated', memoryId: target.memoryId };
+}
+async function supersedeCanonicalFact(deps, targetMemoryId, userId, fact, embedding, sourceSite, sourceUrl, episodeId, contradictionConfidence, trustScore, logicalTimestamp, workspace) {
+    const target = await ensureClaimTarget(deps, userId, targetMemoryId);
+    await deps.stores.memory.expireMemory(userId, target.memoryId);
+    const newMemoryId = await storeProjection(deps, userId, fact, embedding, sourceSite, sourceUrl, episodeId, trustScore ?? 1.0, {
+        logicalTimestamp,
+        workspace,
+    });
+    if (!newMemoryId)
+        return { outcome: 'skipped', memoryId: null };
+    const lineage = await emitLineageEvent({ claims: deps.stores.claim, repo: deps.stores.memory, config: deps.config }, {
+        kind: 'canonical-supersede',
+        userId,
+        fact,
+        embedding,
+        sourceSite,
+        sourceUrl,
+        episodeId,
+        logicalTimestamp,
+        target,
+        newMemoryId,
+        contradictionConfidence,
+    });
+    if (!lineage?.cmoId) {
+        throw new Error(`AUDN SUPERSEDE failed: missing successor canonical object for "${target.memoryId}"`);
+    }
+    await deps.stores.memory.updateMemoryMetadata(userId, newMemoryId, { cmo_id: lineage.cmoId });
+    if (deps.config.lessonsEnabled && deps.stores.lesson && contradictionConfidence) {
+        recordContradictionLesson(deps.stores.lesson, {
+            userId, content: fact.fact, sourceSite,
+            contradictionConfidence, supersededMemoryId: target.memoryId,
+        }).catch((err) => console.error('Lesson recording failed:', err));
+    }
+    return { outcome: 'deleted', memoryId: newMemoryId };
+}
+/** Handle AUDN DELETE: soft-delete the old memory without creating a replacement. */
+async function deleteCanonicalFact(deps, targetMemoryId, userId, fact, sourceSite, sourceUrl, episodeId, contradictionConfidence, logicalTimestamp) {
+    const target = await ensureClaimTarget(deps, userId, targetMemoryId);
+    const targetMemory = await deps.stores.memory.getMemoryIncludingDeleted(target.memoryId, userId);
+    if (!targetMemory)
+        return { outcome: 'skipped', memoryId: null };
+    await deps.stores.memory.softDeleteMemory(userId, target.memoryId);
+    await emitLineageEvent({ claims: deps.stores.claim, repo: deps.stores.memory, config: deps.config }, {
+        kind: 'canonical-delete',
+        userId,
+        fact,
+        sourceSite,
+        sourceUrl,
+        episodeId,
+        logicalTimestamp,
+        target,
+        targetEmbedding: targetMemory.embedding,
+        contradictionConfidence,
+    });
+    if (deps.config.auditLoggingEnabled) {
+        emitAuditEvent('memory:delete', userId, {
+            reason: 'audn-delete', targetMemoryId: target.memoryId, contradictionConfidence,
+        }, { memoryId: target.memoryId });
+    }
+    return { outcome: 'deleted', memoryId: null };
+}
+async function recordNoop(deps, targetMemoryId, candidateIds, userId, episodeId, quoteText) {
+    if (!targetMemoryId || !candidateIds.has(targetMemoryId))
+        return { outcome: 'skipped', memoryId: null };
+    try {
+        const target = await ensureClaimTarget(deps, userId, targetMemoryId);
+        await deps.stores.claim.addEvidence({ claimVersionId: target.versionId, episodeId, memoryId: target.memoryId, quoteText });
+    }
+    catch {
+        // Target memory may not exist if AUDN decision was cached from a previous run.
+        // Safe to skip -- NOOP means "do nothing."
+    }
+    return { outcome: 'skipped', memoryId: null };
+}
+const QUOTED_LITERAL_PATTERN = /["""'\u2018\u2019\u201C\u201D]([^"""'\u2018\u2019\u201C\u201D]{2,80})["""'\u2018\u2019\u201C\u201D]/g;
+function sharesQuotedLiteral(factText, candidateContent) {
+    const quotedLiterals = extractQuotedLiterals(factText);
+    if (quotedLiterals.length === 0)
+        return true;
+    const lowerCandidate = candidateContent.toLowerCase();
+    return quotedLiterals.every((literal) => lowerCandidate.includes(literal.toLowerCase()));
+}
+function extractQuotedLiterals(text) {
+    const literals = [];
+    let match;
+    while ((match = QUOTED_LITERAL_PATTERN.exec(text)) !== null) {
+        literals.push(match[1]);
+    }
+    return literals;
+}
+/**
+ * Fast-path AUDN: skip the LLM call for clear-cut embedding similarity cases.
+ * sim >= 0.95: near-duplicate -> NOOP (skip storing).
+ * Returns null when the case is ambiguous and needs full LLM AUDN.
+ */
+function tryFastAUDN(factText, candidates, runtimeConfig) {
+    if (!runtimeConfig.fastAudnEnabled)
+        return null;
+    const topCandidate = candidates.reduce((best, c) => (c.similarity > best.similarity ? c : best), candidates[0]);
+    if (!sharesQuotedLiteral(factText, topCandidate.content)) {
+        return null;
+    }
+    if (topCandidate.similarity >= runtimeConfig.fastAudnDuplicateThreshold) {
+        console.log(`[fast-audn] NOOP: sim=${topCandidate.similarity.toFixed(4)} >= ${runtimeConfig.fastAudnDuplicateThreshold} (near-duplicate of ${topCandidate.id})`);
+        return {
+            action: 'NOOP',
+            targetMemoryId: topCandidate.id,
+            updatedContent: null,
+            contradictionConfidence: null,
+        };
+    }
+    return null;
+}

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

@@ -0,0 +1,93 @@
+/**
+ * CRUD operations and auxiliary methods extracted from MemoryService.
+ * Covers list, get, delete, stats, consolidation, decay, audit, lessons, and backfill.
+ */
+import { type ClaimSlotInput } from '../db/claim-repository.js';
+import { type ConsolidationResult, type ConsolidationExecutionResult } from './consolidation-service.js';
+import { type DecayResult, type CapCheckResult } from './memory-lifecycle.js';
+import { type ReconciliationResult } from './deferred-audn.js';
+import type { AuditTrailEntry, MutationSummary } from '../db/repository-types.js';
+import type { MemoryServiceDeps } from './memory-service-types.js';
+export interface ClaimSlotBackfillResult {
+    scanned: number;
+    updated: number;
+}
+export declare function listMemories(deps: MemoryServiceDeps, userId: string, limit?: number, offset?: number, sourceSite?: string, episodeId?: string): Promise<import("../index.js").MemoryRow[]>;
+export declare function listMemoriesInWorkspace(deps: MemoryServiceDeps, workspaceId: string, limit: number | undefined, offset: number | undefined, callerAgentId: string): Promise<import("../index.js").MemoryRow[]>;
+export declare function getMemory(deps: MemoryServiceDeps, id: string, userId: string): Promise<import("../index.js").MemoryRow | null>;
+export declare function getMemoryInWorkspace(deps: MemoryServiceDeps, id: string, workspaceId: string, callerAgentId: string): Promise<import("../index.js").MemoryRow | null>;
+/** Workspace delete enforces visibility: returns false if caller can't see the memory. */
+export declare function deleteMemoryInWorkspace(deps: MemoryServiceDeps, id: string, workspaceId: string, callerAgentId: string): Promise<boolean>;
+/** Expand staged summaries to full content for on-demand loading. */
+export declare function expandMemories(deps: MemoryServiceDeps, userId: string, memoryIds: string[]): Promise<Array<{
+    id: string;
+    content: string;
+}>>;
+export declare function expandMemoriesInWorkspace(deps: MemoryServiceDeps, workspaceId: string, memoryIds: string[], callerAgentId: string): Promise<Array<{
+    id: string;
+    content: string;
+}>>;
+export declare function deleteMemory(deps: MemoryServiceDeps, id: string, userId: string): Promise<void>;
+/**
+ * Delete all memories, episodes, claims, and related data for a user + source_site,
+ * and tombstone (soft-delete) every `raw_documents` row registered against the
+ * same source. Surgical reset scoped to a single source -- does NOT wipe the whole user.
+ */
+export declare function resetBySource(deps: MemoryServiceDeps, userId: string, sourceSite: string): Promise<{
+    deletedMemories: number;
+    deletedEpisodes: number;
+    deletedDocuments: number;
+}>;
+export declare function getStats(deps: MemoryServiceDeps, userId: string): Promise<{
+    count: number;
+    avgImportance: number;
+    sourceDistribution: Record<string, number>;
+}>;
+/** Identify memory clusters that are candidates for consolidation. */
+export declare function consolidate(deps: MemoryServiceDeps, userId: string): Promise<ConsolidationResult>;
+/** Execute consolidation: synthesize clusters via LLM and archive originals. */
+export declare function performExecuteConsolidation(deps: MemoryServiceDeps, userId: string): Promise<ConsolidationExecutionResult>;
+/** Run deferred AUDN reconciliation for a user (background pass). */
+export declare function reconcileDeferred(deps: MemoryServiceDeps, userId: string): Promise<ReconciliationResult>;
+/** Run deferred AUDN reconciliation across all users (batch job). */
+export declare function reconcileDeferredAll(deps: MemoryServiceDeps): Promise<ReconciliationResult>;
+/** Get deferred AUDN reconciliation status for a user. */
+export declare function getDeferredStatus(deps: MemoryServiceDeps, userId: string): Promise<{
+    pending: number;
+    enabled: boolean;
+}>;
+/** Evaluate memories for decay and return archival candidates. */
+export declare function evaluateDecay(deps: MemoryServiceDeps, userId: string, referenceTime?: Date): Promise<DecayResult>;
+/** Archive memories identified by the decay cycle. */
+export declare function archiveDecayed(deps: MemoryServiceDeps, userId: string, memoryIds: string[]): Promise<number>;
+/** Check whether the user's memory count exceeds the configured cap. */
+export declare function checkCap(deps: MemoryServiceDeps, userId: string): Promise<CapCheckResult>;
+/**
+ * Get the full mutation audit trail for a single memory.
+ * Traces back through claim versions to show the complete lifecycle.
+ */
+export declare function getAuditTrail(deps: MemoryServiceDeps, userId: string, memoryId: string): Promise<AuditTrailEntry[]>;
+/** Get aggregate mutation statistics for a user's memory store. */
+export declare function getMutationSummary(deps: MemoryServiceDeps, userId: string): Promise<MutationSummary>;
+/** Get recent mutations for a user, ordered newest first. */
+export declare function getRecentMutations(deps: MemoryServiceDeps, userId: string, limit?: number): Promise<import("../db/repository-types.js").ClaimVersionRow[]>;
+/**
+ * Backfill deterministic relation slots for active legacy claims.
+ * This repairs claims written before canonical slot metadata existed.
+ */
+export declare function backfillClaimSlots(deps: MemoryServiceDeps, userId: string): Promise<ClaimSlotBackfillResult>;
+/** Trace the supersession chain forward from a version. */
+export declare function getReversalChain(deps: MemoryServiceDeps, userId: string, versionId: string): Promise<import("../db/repository-types.js").ClaimVersionRow[]>;
+/** Get all active lessons for a user. */
+export declare function getLessons(deps: MemoryServiceDeps, userId: string): Promise<import("../db/repository-lessons.js").LessonRow[]>;
+/** Get lesson stats for a user. */
+export declare function getLessonStats(deps: MemoryServiceDeps, userId: string): Promise<{
+    totalActive: number;
+    byType: Record<string, number>;
+}>;
+/** Record a user-reported lesson (explicit feedback). */
+export declare function reportLesson(deps: MemoryServiceDeps, userId: string, pattern: string, sourceMemoryIds: string[], severity?: 'low' | 'medium' | 'high' | 'critical'): Promise<string>;
+/** Deactivate a lesson. */
+export declare function deactivateLesson(deps: MemoryServiceDeps, userId: string, lessonId: string): Promise<void>;
+/** Derive a persisted claim slot from existing entity relations. */
+export declare function derivePersistedClaimSlot(deps: MemoryServiceDeps, userId: string, memoryId: string): Promise<ClaimSlotInput | null>;