@atomicmemory/core 1.0.0

package/dist/services/memory-crud.js

@@ -0,0 +1,255 @@
+/**
+ * CRUD operations and auxiliary methods extracted from MemoryService.
+ * Covers list, get, delete, stats, consolidation, decay, audit, lessons, and backfill.
+ */
+import { config } from '../config.js';
+import { findConsolidationCandidates, executeConsolidation } from './consolidation-service.js';
+import { evaluateDecayCandidates, checkMemoryCap } from './memory-lifecycle.js';
+import { emitAuditEvent } from './audit-events.js';
+import { reconcileUser, reconcileAll, getReconciliationStatus } from './deferred-audn.js';
+import { buildPersistedRelationClaimSlot } from './claim-slotting.js';
+import { cleanupManagedBlobs, ManagedBlobCleanupError } from '../storage/cleanup.js';
+import { singleStoreRegistry } from '../storage/store-registry.js';
+import { listOrphanedManagedBlobsBySource, } from '../db/raw-document-blob-repository.js';
+import { markCleanupFailedAndSyncArtifact, markCleanupSuccessAndSyncArtifact, } from '../db/raw-doc-artifact-sync.js';
+export async function listMemories(deps, userId, limit = 20, offset = 0, sourceSite, episodeId) {
+    return deps.stores.memory.listMemories(userId, limit, offset, sourceSite, episodeId);
+}
+export async function listMemoriesInWorkspace(deps, workspaceId, limit = 20, offset = 0, callerAgentId) {
+    return deps.stores.memory.listMemoriesInWorkspace(workspaceId, limit, offset, callerAgentId);
+}
+export async function getMemory(deps, id, userId) {
+    return deps.stores.memory.getMemory(id, userId);
+}
+export async function getMemoryInWorkspace(deps, id, workspaceId, callerAgentId) {
+    return deps.stores.memory.getMemoryInWorkspace(id, workspaceId, callerAgentId);
+}
+/** Workspace delete enforces visibility: returns false if caller can't see the memory. */
+export async function deleteMemoryInWorkspace(deps, id, workspaceId, callerAgentId) {
+    const memory = await deps.stores.memory.getMemoryInWorkspace(id, workspaceId, callerAgentId);
+    if (!memory)
+        return false;
+    await deps.stores.memory.softDeleteMemoryInWorkspace(id, workspaceId);
+    if (config.auditLoggingEnabled) {
+        emitAuditEvent('memory:delete', '', {}, { memoryId: id, workspaceId });
+    }
+    return true;
+}
+/** Expand staged summaries to full content for on-demand loading. */
+export async function expandMemories(deps, userId, memoryIds) {
+    const fetched = await Promise.all(memoryIds.map((id) => deps.stores.memory.getMemory(id, userId)));
+    return fetched.filter(Boolean).map((m) => ({ id: m.id, content: m.content }));
+}
+export async function expandMemoriesInWorkspace(deps, workspaceId, memoryIds, callerAgentId) {
+    const fetched = await Promise.all(memoryIds.map((id) => deps.stores.memory.getMemoryInWorkspace(id, workspaceId, callerAgentId)));
+    return fetched.filter(Boolean).map((m) => ({ id: m.id, content: m.content }));
+}
+export async function deleteMemory(deps, id, userId) {
+    const version = await deps.stores.claim.getClaimVersionByMemoryId(userId, id);
+    const target = version ? { claimId: version.claim_id, versionId: version.id } : null;
+    await deps.stores.memory.softDeleteMemory(userId, id);
+    if (config.auditLoggingEnabled) {
+        emitAuditEvent('memory:delete', userId, {}, { memoryId: id });
+    }
+    if (!target)
+        return;
+    await deps.stores.claim.supersedeClaimVersion(userId, target.versionId, null);
+    await deps.stores.claim.invalidateClaim(userId, target.claimId);
+}
+/**
+ * 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 async function resetBySource(deps, userId, sourceSite) {
+    const result = await deps.stores.memory.deleteBySource(userId, sourceSite);
+    // Cleanup target: blobs the cascade just tombstoned, OR — when the
+    // cascade found nothing fresh to soft-delete (typical retry path) —
+    // the orphan blobs left behind by a previously-failed cleanup pass
+    // for this source. Without this lookup, a retry of source reset
+    // could see zero active rows, skip cleanup, and report success
+    // while bytes were still on disk.
+    const blobsToClean = result.blobs.length > 0
+        ? result.blobs
+        : await listOrphanedManagedBlobsBySource(deps.stores.pool, userId, sourceSite);
+    if (blobsToClean.length > 0) {
+        const registry = deps.storeRegistry ?? singleStoreRegistry(deps.rawContentStore ?? null);
+        const cleanup = await cleanupManagedBlobs(registry, blobsToClean);
+        // Mark partial successes terminal *before* throwing. A mixed-result
+        // cleanup that doesn't record the wins would leak retry work onto
+        // rows that are already clean. The marker is chosen by the
+        // adapter's `semantics` field — `'deleted'` → `blob_deleted`,
+        // `'unpinned'`/`'tombstoned'` → `blob_tombstoned` (Phase 4a §1).
+        for (const success of cleanup.successes) {
+            await markCleanupSuccessAndSyncArtifact(deps.stores.pool, {
+                userId,
+                rawDocumentId: success.rawDocumentId,
+                storageUri: success.storageUri,
+                semantics: success.semantics,
+            });
+        }
+        if (cleanup.failures.length > 0) {
+            for (const failure of cleanup.failures) {
+                await markCleanupFailedAndSyncArtifact(deps.stores.pool, {
+                    userId,
+                    rawDocumentId: failure.rawDocumentId,
+                });
+            }
+            throw new ManagedBlobCleanupError(cleanup);
+        }
+    }
+    if (config.auditLoggingEnabled) {
+        emitAuditEvent('memory:reset-source', userId, {
+            sourceSite,
+            deletedMemories: result.deletedMemories,
+            deletedEpisodes: result.deletedEpisodes,
+            deletedDocuments: result.deletedDocuments,
+        });
+    }
+    return {
+        deletedMemories: result.deletedMemories,
+        deletedEpisodes: result.deletedEpisodes,
+        deletedDocuments: result.deletedDocuments,
+    };
+}
+export async function getStats(deps, userId) {
+    return deps.stores.memory.getMemoryStats(userId);
+}
+/** Identify memory clusters that are candidates for consolidation. */
+export async function consolidate(deps, userId) {
+    return findConsolidationCandidates(deps.stores.memory, userId);
+}
+/** Execute consolidation: synthesize clusters via LLM and archive originals. */
+export async function performExecuteConsolidation(deps, userId) {
+    return executeConsolidation(deps.stores.memory, deps.stores.claim, userId, undefined, deps.config);
+}
+/** Run deferred AUDN reconciliation for a user (background pass). */
+export async function reconcileDeferred(deps, userId) {
+    return reconcileUser(deps.stores.pool, deps.stores.memory, userId);
+}
+/** Run deferred AUDN reconciliation across all users (batch job). */
+export async function reconcileDeferredAll(deps) {
+    return reconcileAll(deps.stores.pool, deps.stores.memory);
+}
+/** Get deferred AUDN reconciliation status for a user. */
+export async function getDeferredStatus(deps, userId) {
+    return getReconciliationStatus(deps.stores.pool, userId);
+}
+/** Evaluate memories for decay and return archival candidates. */
+export async function evaluateDecay(deps, userId, referenceTime) {
+    const memories = await deps.stores.memory.listMemories(userId, 500, 0);
+    const decayConfig = {
+        retentionThreshold: config.decayRetentionThreshold,
+        importanceWeight: 0.4, recencyWeight: 0.4, accessWeight: 0.2,
+        minAgeMs: config.decayMinAgeDays * 24 * 60 * 60 * 1000,
+    };
+    return evaluateDecayCandidates(memories, referenceTime ?? new Date(), decayConfig);
+}
+/** Archive memories identified by the decay cycle. */
+export async function archiveDecayed(deps, userId, memoryIds) {
+    for (const id of memoryIds) {
+        await deps.stores.memory.softDeleteMemory(userId, id);
+        if (config.auditLoggingEnabled)
+            emitAuditEvent('memory:delete', userId, { reason: 'decay' }, { memoryId: id });
+    }
+    return memoryIds.length;
+}
+/** Check whether the user's memory count exceeds the configured cap. */
+export async function checkCap(deps, userId) {
+    const count = await deps.stores.memory.countMemories(userId);
+    return checkMemoryCap(count, { maxMemories: config.memoryCapMax, warnRatio: config.memoryCapWarnRatio });
+}
+/**
+ * Get the full mutation audit trail for a single memory.
+ * Traces back through claim versions to show the complete lifecycle.
+ */
+export async function getAuditTrail(deps, userId, memoryId) {
+    const found = await deps.stores.claim.findClaimByMemoryId(userId, memoryId);
+    if (!found)
+        return [];
+    return found.versions.map((v) => ({
+        versionId: v.id,
+        claimId: v.claim_id,
+        content: v.content,
+        mutationType: v.mutation_type,
+        mutationReason: v.mutation_reason,
+        actorModel: v.actor_model,
+        contradictionConfidence: v.contradiction_confidence,
+        previousVersionId: v.previous_version_id,
+        supersededByVersionId: v.superseded_by_version_id,
+        validFrom: v.valid_from,
+        validTo: v.valid_to,
+        memoryId: v.memory_id,
+    }));
+}
+/** Get aggregate mutation statistics for a user's memory store. */
+export async function getMutationSummary(deps, userId) {
+    return deps.stores.claim.getUserMutationSummary(userId);
+}
+/** Get recent mutations for a user, ordered newest first. */
+export async function getRecentMutations(deps, userId, limit = 20) {
+    return deps.stores.claim.getRecentMutations(userId, limit);
+}
+/**
+ * Backfill deterministic relation slots for active legacy claims.
+ * This repairs claims written before canonical slot metadata existed.
+ */
+export async function backfillClaimSlots(deps, userId) {
+    if (!deps.stores.entity) {
+        return { scanned: 0, updated: 0 };
+    }
+    const candidates = await deps.stores.claim.listClaimsMissingSlots(userId);
+    let updated = 0;
+    for (const candidate of candidates) {
+        const slot = await derivePersistedClaimSlot(deps, candidate.userId, candidate.memoryId);
+        if (!slot)
+            continue;
+        await deps.stores.claim.updateClaimSlot(candidate.userId, candidate.claimId, slot);
+        updated += 1;
+    }
+    return { scanned: candidates.length, updated };
+}
+/** Trace the supersession chain forward from a version. */
+export async function getReversalChain(deps, userId, versionId) {
+    return deps.stores.claim.getReversalChain(userId, versionId);
+}
+/** Get all active lessons for a user. */
+export async function getLessons(deps, userId) {
+    if (!deps.stores.lesson)
+        return [];
+    const { getUserLessons } = await import('./lesson-service.js');
+    return getUserLessons(deps.stores.lesson, userId);
+}
+/** Get lesson stats for a user. */
+export async function getLessonStats(deps, userId) {
+    if (!deps.stores.lesson)
+        return { totalActive: 0, byType: {} };
+    const { getLessonStats: getStats } = await import('./lesson-service.js');
+    return getStats(deps.stores.lesson, userId);
+}
+/** Record a user-reported lesson (explicit feedback). */
+export async function reportLesson(deps, userId, pattern, sourceMemoryIds, severity) {
+    if (!deps.stores.lesson)
+        throw new Error('Lessons are not enabled');
+    const { recordUserReportedLesson } = await import('./lesson-service.js');
+    return recordUserReportedLesson(deps.stores.lesson, userId, pattern, sourceMemoryIds, severity);
+}
+/** Deactivate a lesson. */
+export async function deactivateLesson(deps, userId, lessonId) {
+    if (!deps.stores.lesson)
+        throw new Error('Lessons are not enabled');
+    return deps.stores.lesson.deactivateLesson(userId, lessonId);
+}
+/** Derive a persisted claim slot from existing entity relations. */
+export async function derivePersistedClaimSlot(deps, userId, memoryId) {
+    if (!deps.stores.entity)
+        return null;
+    const relations = await deps.stores.entity.getRelationsForMemory(userId, memoryId);
+    if (relations.length === 0)
+        return null;
+    return buildPersistedRelationClaimSlot(relations.map((relation) => ({
+        sourceEntityId: relation.source_entity_id,
+        targetEntityId: relation.target_entity_id,
+        relationType: relation.relation_type,
+    })));
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Top-level ingest pipeline logic: performIngest, performQuickIngest, performWorkspaceIngest.
+ * Delegates AUDN resolution to memory-audn.ts and storage to memory-storage.ts.
+ */
+import type { MemoryMetadata, WorkspaceContext } from '../db/repository-types.js';
+import type { IngestResult, MemoryServiceDeps } from './memory-service-types.js';
+/** Full consensus-based ingest pipeline. */
+export declare function performIngest(deps: MemoryServiceDeps, userId: string, conversationText: string, sourceSite: string, sourceUrl?: string, sessionTimestamp?: Date): Promise<IngestResult>;
+/**
+ * Fast ingest path for UC2 (background capture).
+ * Uses rule-based extraction (~50ms) instead of LLM consensus (~22s).
+ */
+export declare function performQuickIngest(deps: MemoryServiceDeps, userId: string, conversationText: string, sourceSite: string, sourceUrl?: string, sessionTimestamp?: Date): Promise<IngestResult>;
+/**
+ * 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.
+ */
+export declare function performStoreVerbatim(deps: MemoryServiceDeps, userId: string, content: string, sourceSite: string, sourceUrl?: string, metadata?: MemoryMetadata): Promise<IngestResult>;
+/** Workspace-scoped ingest: stores memories tagged with workspace_id and agent_id. */
+export declare function performWorkspaceIngest(deps: MemoryServiceDeps, userId: string, conversationText: string, sourceSite: string, sourceUrl: string | undefined, workspace: WorkspaceContext, sessionTimestamp?: Date): Promise<IngestResult>;

package/dist/services/memory-ingest.js

@@ -0,0 +1,249 @@
+/**
+ * Top-level ingest pipeline logic: performIngest, performQuickIngest, performWorkspaceIngest.
+ * Delegates AUDN resolution to memory-audn.ts and storage to memory-storage.ts.
+ */
+import { embedText } from './embedding.js';
+import { consensusExtractFacts } from './consensus-extraction.js';
+import { quickExtractFacts } from './quick-extraction.js';
+import { IngestTraceCollector } from './ingest-trace.js';
+import { assessWriteSecurity } from './write-security.js';
+import { timed } from './timing.js';
+import { runPostWriteProcessors } from './ingest-post-write.js';
+import { extractLiteralsFromFact } from './literal-extractor.js';
+import { processFactThroughPipeline } from './ingest-fact-pipeline.js';
+import { resolveSessionDate } from './session-date.js';
+import { maybeRebuildProfileForUser } from './user-profile-builder.js';
+import { maybeExtractEntityAttributesForIngest } from './entity-attribute-extractor.js';
+/** Enqueue a reflection job for (userId, conversationId) when the feature gate is on. */
+async function maybeEnqueueReflectionJob(reflectionJobs, reflectEnabled, userId, conversationId) {
+    if (!reflectEnabled || !reflectionJobs)
+        return;
+    try {
+        await reflectionJobs.enqueue(userId, conversationId);
+    }
+    catch (e) {
+        // Enqueue failure must NEVER block the ingest response.
+        console.error('[memory-ingest] reflection enqueue failed:', e);
+    }
+}
+function createIngestAccumulator() {
+    return {
+        counters: { stored: 0, updated: 0, deleted: 0, skipped: 0, preserved_contradiction: 0 },
+        storedMemoryIds: [],
+        updatedMemoryIds: [],
+        memoryIds: [],
+        embeddingCache: new Map(),
+    };
+}
+/** Record a single fact result into the accumulator. */
+function accumulateFactResult(acc, result) {
+    if (result.memoryId) {
+        acc.memoryIds.push(result.memoryId);
+        if (result.outcome === 'stored')
+            acc.storedMemoryIds.push(result.memoryId);
+        else if (result.outcome === 'updated')
+            acc.updatedMemoryIds.push(result.memoryId);
+        // BEAM CR fix: bilateral preservation keeps both sides — the returned
+        // memoryId is the NEW row (the existing counterpart already lives in
+        // memories). Treat as "stored" for downstream linking/processing.
+        else if (result.outcome === 'preserved_contradiction')
+            acc.storedMemoryIds.push(result.memoryId);
+        if (result.embedding)
+            acc.embeddingCache.set(result.memoryId, result.embedding);
+    }
+    acc.counters[result.outcome]++;
+}
+function buildIngestResult(episodeId, factsCount, acc, linksCreated, compositesCreated) {
+    return {
+        episodeId, factsExtracted: factsCount,
+        memoriesStored: acc.counters.stored, memoriesUpdated: acc.counters.updated,
+        memoriesDeleted: acc.counters.deleted, memoriesSkipped: acc.counters.skipped,
+        storedMemoryIds: acc.storedMemoryIds, updatedMemoryIds: acc.updatedMemoryIds,
+        memoryIds: acc.memoryIds, linksCreated, compositesCreated,
+    };
+}
+function finalizeIngestResult(episodeId, factsCount, acc, linksCreated, compositesCreated, traceCollector, traceMetadata) {
+    return {
+        ...buildIngestResult(episodeId, factsCount, acc, linksCreated, compositesCreated),
+        ingestTraceId: traceCollector.finalize(traceMetadata),
+    };
+}
+/** Full consensus-based ingest pipeline. */
+export async function performIngest(deps, userId, conversationText, sourceSite, sourceUrl = '', sessionTimestamp) {
+    const ingestStart = performance.now();
+    const logicalSessionTimestamp = resolveSessionDate(sessionTimestamp, conversationText);
+    const episodeId = await timed('ingest.store-episode', () => deps.stores.episode.storeEpisode({ userId, content: conversationText, sourceSite, sourceUrl }));
+    const facts = await timed('ingest.extract', () => consensusExtractFacts(conversationText, deps.config));
+    const traceCollector = new IngestTraceCollector(deps.config.ingestTraceEnabled);
+    const acc = createIngestAccumulator();
+    const supersededTargets = new Set();
+    const entropyCtx = { seenEntities: new Set(), previousEmbedding: null };
+    const storedFacts = [];
+    for (const fact of facts) {
+        const result = await timed('ingest.fact', () => processFactThroughPipeline(deps, userId, fact, sourceSite, sourceUrl, episodeId, { entropyGate: true, fullAudn: true, supersededTargets, entropyCtx, logicalTimestamp: logicalSessionTimestamp, timingPrefix: 'ingest', traceCollector }));
+        accumulateFactResult(acc, result);
+        if (result.memoryId)
+            storedFacts.push({ memoryId: result.memoryId, fact });
+    }
+    const postWrite = await runPostWriteProcessors(deps, userId, {
+        episodeId, sourceSite, sourceUrl, storedFacts,
+        memoryIds: acc.memoryIds, embeddingCache: acc.embeddingCache,
+        sessionTimestamp: logicalSessionTimestamp, compositesEnabled: deps.config.compositeGroupingEnabled,
+        timingPrefix: 'ingest',
+        chunkText: conversationText,
+    });
+    // Phase 2: literal extraction for IE/KU specialist.
+    // Awaited so the container doesn't exit before writes complete.
+    // Per-fact failures are logged and never block subsequent facts or the response.
+    if (deps.config.phase2SpecialistsEnabled && deps.stores.entityValues) {
+        const entityValues = deps.stores.entityValues;
+        const model = deps.config.llmModel;
+        await Promise.allSettled(acc.storedMemoryIds.map(async (memoryId) => {
+            const stored = storedFacts.find((sf) => sf.memoryId === memoryId);
+            if (!stored)
+                return;
+            try {
+                await extractLiteralsFromFact({ values: entityValues, model }, {
+                    userId,
+                    factId: memoryId,
+                    factText: stored.fact.fact,
+                    observedAt: logicalSessionTimestamp ?? new Date(),
+                });
+            }
+            catch (e) {
+                console.error('[literal-extractor] extraction failed for fact', memoryId, e);
+            }
+        }));
+    }
+    if (deps.config.userProfileChannelEnabled) {
+        void maybeRebuildProfileForUser(deps, userId, acc.storedMemoryIds);
+    }
+    if (deps.config.entityAttributesEnabled) {
+        void maybeExtractEntityAttributesForIngest(deps, userId, conversationText, logicalSessionTimestamp, acc.storedMemoryIds);
+    }
+    await maybeEnqueueReflectionJob(deps.reflectionJobs, deps.reflectEnabled, userId, episodeId);
+    console.log(`[timing] ingest.total: ${(performance.now() - ingestStart).toFixed(1)}ms (${facts.length} facts, ${postWrite.compositesCreated} composites, topic=${postWrite.topicAbstractionApplied})`);
+    return finalizeIngestResult(episodeId, facts.length, acc, postWrite.linksCreated, postWrite.compositesCreated, traceCollector, { mode: 'full', userId, sourceSite, sourceUrl, episodeId, factsExtracted: facts.length });
+}
+/**
+ * Fast ingest path for UC2 (background capture).
+ * Uses rule-based extraction (~50ms) instead of LLM consensus (~22s).
+ */
+export async function performQuickIngest(deps, userId, conversationText, sourceSite, sourceUrl = '', sessionTimestamp) {
+    const ingestStart = performance.now();
+    const logicalSessionTimestamp = resolveSessionDate(sessionTimestamp, conversationText);
+    const episodeId = await deps.stores.episode.storeEpisode({ userId, content: conversationText, sourceSite, sourceUrl });
+    const facts = timed('quick-ingest.extract', () => Promise.resolve(quickExtractFacts(conversationText)));
+    const extractedFacts = await facts;
+    const traceCollector = new IngestTraceCollector(deps.config.ingestTraceEnabled);
+    const acc = createIngestAccumulator();
+    for (const fact of extractedFacts) {
+        const result = await timed('quick-ingest.fact', () => processFactThroughPipeline(deps, userId, fact, sourceSite, sourceUrl, episodeId, { entropyGate: false, fullAudn: false, supersededTargets: new Set(), entropyCtx: { seenEntities: new Set(), previousEmbedding: null }, logicalTimestamp: logicalSessionTimestamp, timingPrefix: 'quick-ingest', traceCollector }));
+        accumulateFactResult(acc, result);
+    }
+    const postWrite = await runPostWriteProcessors(deps, userId, {
+        episodeId, sourceSite, sourceUrl, storedFacts: [],
+        memoryIds: acc.memoryIds, embeddingCache: acc.embeddingCache,
+        sessionTimestamp: logicalSessionTimestamp, compositesEnabled: false,
+        timingPrefix: 'quick-ingest',
+        chunkText: conversationText,
+    });
+    console.log(`[timing] quick-ingest.total: ${(performance.now() - ingestStart).toFixed(1)}ms (${extractedFacts.length} facts, ${acc.counters.stored} stored, ${acc.counters.skipped} skipped)`);
+    return finalizeIngestResult(episodeId, extractedFacts.length, acc, postWrite.linksCreated, 0, traceCollector, { mode: 'quick', userId, sourceSite, sourceUrl, episodeId, factsExtracted: extractedFacts.length });
+}
+/**
+ * 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.
+ */
+export async function performStoreVerbatim(deps, userId, content, sourceSite, sourceUrl = '', metadata) {
+    const episodeId = await deps.stores.episode.storeEpisode({ userId, content, sourceSite, sourceUrl });
+    const embedding = await embedText(content);
+    const writeSecurity = assessWriteSecurity(content, sourceSite, deps.config);
+    const trustScore = writeSecurity.allowed ? writeSecurity.trust.score : 0.5;
+    const traceCollector = new IngestTraceCollector(deps.config.ingestTraceEnabled);
+    const memoryId = await deps.stores.memory.storeMemory({
+        userId,
+        content,
+        embedding,
+        memoryType: 'semantic',
+        importance: 0.5,
+        sourceSite,
+        sourceUrl,
+        episodeId,
+        status: 'active',
+        keywords: '',
+        summary: content.slice(0, 200),
+        trustScore,
+        metadata,
+    });
+    traceCollector.record({
+        factText: content,
+        headline: content.slice(0, 80),
+        factType: 'verbatim',
+        importance: 0.5,
+        writeSecurity: {
+            allowed: writeSecurity.allowed,
+            blockedBy: writeSecurity.blockedBy,
+            trustScore: writeSecurity.trust.score,
+        },
+        decision: {
+            source: 'verbatim',
+            action: 'ADD',
+            reasonCode: 'verbatim-store',
+            targetMemoryId: null,
+        },
+        outcome: 'stored',
+        memoryId,
+    });
+    return {
+        episodeId,
+        factsExtracted: 1,
+        memoriesStored: 1,
+        memoriesUpdated: 0,
+        memoriesDeleted: 0,
+        memoriesSkipped: 0,
+        storedMemoryIds: [memoryId],
+        updatedMemoryIds: [],
+        memoryIds: [memoryId],
+        linksCreated: 0,
+        compositesCreated: 0,
+        ingestTraceId: traceCollector.finalize({ mode: 'verbatim', userId, sourceSite, sourceUrl, episodeId, factsExtracted: 1 }),
+    };
+}
+/** Workspace-scoped ingest: stores memories tagged with workspace_id and agent_id. */
+export async function performWorkspaceIngest(deps, userId, conversationText, sourceSite, sourceUrl = '', workspace, sessionTimestamp) {
+    const ingestStart = performance.now();
+    const logicalSessionTimestamp = resolveSessionDate(sessionTimestamp, conversationText);
+    const episodeId = await timed('ws-ingest.store-episode', () => deps.stores.episode.storeEpisode({
+        userId, content: conversationText, sourceSite, sourceUrl,
+        workspaceId: workspace.workspaceId, agentId: workspace.agentId,
+    }));
+    const facts = await timed('ws-ingest.extract', () => consensusExtractFacts(conversationText, deps.config));
+    const traceCollector = new IngestTraceCollector(deps.config.ingestTraceEnabled);
+    const acc = createIngestAccumulator();
+    const supersededTargets = new Set();
+    const entropyCtx = { seenEntities: new Set(), previousEmbedding: null };
+    for (const fact of facts) {
+        const result = await timed('ws-ingest.fact', () => processFactThroughPipeline(deps, userId, fact, sourceSite, sourceUrl, episodeId, {
+            workspace,
+            entropyGate: false,
+            fullAudn: true,
+            supersededTargets,
+            entropyCtx,
+            logicalTimestamp: logicalSessionTimestamp,
+            timingPrefix: 'ws-ingest',
+            traceCollector,
+        }));
+        accumulateFactResult(acc, result);
+    }
+    const postWrite = await runPostWriteProcessors(deps, userId, {
+        episodeId, sourceSite, sourceUrl, storedFacts: [],
+        memoryIds: acc.memoryIds, embeddingCache: acc.embeddingCache,
+        sessionTimestamp: logicalSessionTimestamp, compositesEnabled: false,
+        timingPrefix: 'ws-ingest',
+        chunkText: conversationText,
+    });
+    console.log(`[timing] ws-ingest.total: ${(performance.now() - ingestStart).toFixed(1)}ms (${facts.length} facts, workspace=${workspace.workspaceId})`);
+    return finalizeIngestResult(episodeId, facts.length, acc, postWrite.linksCreated, 0, traceCollector, { mode: 'workspace', userId, sourceSite, sourceUrl, episodeId, factsExtracted: facts.length });
+}

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

@@ -0,0 +1,75 @@
+/**
+ * Memory lifecycle management: decay cycle and memory count cap.
+ *
+ * Decay cycle: Computes a retention score for each memory using the same
+ * three-signal formula as retrieval scoring (similarity excluded since there's
+ * no query). Memories below the retention threshold are archived (soft-deleted).
+ * This implements the Ebbinghaus forgetting curve for long-term store health.
+ *
+ * Memory count cap: Checks whether a user's active memory count exceeds
+ * a configured limit and returns a recommendation for whether consolidation
+ * or decay should run.
+ *
+ * Both features are pure functions over memory data + config — they compute
+ * what should happen but let the caller decide when to act.
+ */
+import type { MemoryRow } from '../db/repository-types.js';
+export interface DecayConfig {
+    /** Retention score below which memories are archived. */
+    retentionThreshold: number;
+    /** Weight for importance in retention score. */
+    importanceWeight: number;
+    /** Weight for recency in retention score. */
+    recencyWeight: number;
+    /** Weight for access frequency in retention score. */
+    accessWeight: number;
+    /** Minimum age in milliseconds before a memory can be decayed. */
+    minAgeMs: number;
+}
+export declare const DEFAULT_DECAY_CONFIG: DecayConfig;
+export interface DecayCandidate {
+    id: string;
+    content: string;
+    retentionScore: number;
+    importance: number;
+    daysSinceAccess: number;
+    accessCount: number;
+}
+export interface DecayResult {
+    memoriesEvaluated: number;
+    candidatesForArchival: DecayCandidate[];
+    retentionThreshold: number;
+    avgRetentionScore: number;
+}
+/**
+ * Compute the retention score for a single memory.
+ *
+ * Formula: importanceWeight * importance + recencyWeight * recency + accessWeight * accessFreq
+ * Where recency = exp(-timeSinceAccess / TAU) and accessFreq = min(1, accessCount / 10).
+ */
+export declare function computeRetentionScore(memory: Pick<MemoryRow, 'importance' | 'last_accessed_at' | 'access_count' | 'trust_score'>, referenceTime: Date, decayConfig: DecayConfig): number;
+/**
+ * Evaluate a batch of memories and identify those below the retention threshold.
+ * Does not modify any data — returns candidates for the caller to archive.
+ */
+export declare function evaluateDecayCandidates(memories: MemoryRow[], referenceTime: Date, decayConfig?: DecayConfig): DecayResult;
+export interface CapConfig {
+    /** Maximum number of active memories before triggering lifecycle actions. */
+    maxMemories: number;
+    /** Warn threshold as a fraction of maxMemories (0.0-1.0). */
+    warnRatio: number;
+}
+export type CapStatus = 'ok' | 'warn' | 'exceeded';
+export interface CapCheckResult {
+    activeMemories: number;
+    maxMemories: number;
+    status: CapStatus;
+    usageRatio: number;
+    recommendation: CapRecommendation;
+}
+export type CapRecommendation = 'none' | 'consolidate' | 'decay' | 'consolidate-and-decay';
+/**
+ * Check whether a user's memory count is within the configured cap.
+ * Returns a status and recommendation for what lifecycle action to take.
+ */
+export declare function checkMemoryCap(activeMemories: number, capConfig?: CapConfig): CapCheckResult;