@atomicmemory/core 1.0.0

package/dist/db/repository-vector-search.js

@@ -0,0 +1,373 @@
+/**
+ * Swappable vector search backends for the prototype repository.
+ */
+import pgvector from 'pgvector/pg';
+import { config } from '../config.js';
+import { normalizeMemoryRow, normalizeSearchRow, } from './repository-types.js';
+import { RRF_K, buildHybridSearchParams, buildVectorSearchParams, clampUnit } from './query-helpers.js';
+import { cosineSimilarity } from '../vector-math.js';
+export async function searchVectors(pool, userId, queryEmbedding, limit, sourceSite, referenceTime) {
+    if (config.vectorBackend === 'pgvector') {
+        return searchVectorsPg(pool, userId, queryEmbedding, limit, sourceSite, referenceTime);
+    }
+    if (config.vectorBackend === 'ruvector-mock') {
+        return searchVectorsRuvectorMock(pool, userId, queryEmbedding, limit, sourceSite, referenceTime);
+    }
+    return searchVectorsZvecMock(pool, userId, queryEmbedding, limit, sourceSite, referenceTime);
+}
+/**
+ * Hybrid search using Reciprocal Rank Fusion (RRF) to combine vector similarity
+ * with PostgreSQL full-text search. Improves retrieval for keyword-heavy queries
+ * (names, dates, project names) where semantic similarity alone fails.
+ *
+ * Source: 2026-03-07 RAG deep dive (SeekDB link 6, GraphRAG guide link 1).
+ */
+export async function searchHybrid(pool, userId, queryText, queryEmbedding, limit, sourceSite, referenceTime) {
+    if (config.vectorBackend !== 'pgvector') {
+        return searchVectors(pool, userId, queryEmbedding, limit, sourceSite, referenceTime);
+    }
+    return searchHybridPg(pool, userId, queryText, queryEmbedding, limit, sourceSite, referenceTime);
+}
+export async function searchKeyword(pool, userId, queryText, limit, sourceSite) {
+    if (config.vectorBackend !== 'pgvector') {
+        return [];
+    }
+    return searchKeywordPg(pool, userId, queryText, limit, sourceSite);
+}
+export async function findDuplicateVectors(pool, userId, embedding, threshold, limit) {
+    if (config.vectorBackend === 'pgvector') {
+        return findDuplicateVectorsPg(pool, userId, embedding, threshold, limit);
+    }
+    if (config.vectorBackend === 'ruvector-mock') {
+        return findDuplicateVectorsRuvectorMock(pool, userId, embedding, threshold, limit);
+    }
+    return findDuplicateVectorsZvecMock(pool, userId, embedding, threshold, limit);
+}
+/**
+ * Workspace-scoped vector search. Filters by workspace_id and optionally
+ * by agent_id based on AgentScope. Enforces visibility rules when a
+ * callerAgentId is provided.
+ */
+export async function searchVectorsInWorkspace(pool, workspaceId, queryEmbedding, limit, agentScope = 'all', callerAgentId, referenceTime) {
+    const wSim = config.scoringWeightSimilarity;
+    const wImp = config.scoringWeightImportance;
+    const wRec = config.scoringWeightRecency;
+    const rankingMinSimilarity = clampUnit(config.retrievalProfileSettings.rankingMinSimilarity);
+    const refTime = (referenceTime ?? new Date()).toISOString();
+    const params = [
+        pgvector.toSql(queryEmbedding), workspaceId, normalizeLimit(limit),
+        wSim, wImp, wRec, refTime, rankingMinSimilarity,
+    ];
+    let nextParam = 9;
+    const agentClause = buildAgentScopeClause(agentScope, callerAgentId, params, nextParam);
+    nextParam += agentClause.paramsAdded;
+    const visibilityClause = buildVisibilityClauseForSearch(callerAgentId, params, nextParam);
+    const result = await pool.query(`SELECT *,
+       1 - (embedding <=> $1) AS similarity,
+       1 - (embedding <=> $1) AS semantic_similarity,
+       GREATEST(0, LEAST(1, 1 - (embedding <=> $1))) AS relevance,
+       (
+         $4 * (1 - (embedding <=> $1))
+         + $5 * importance
+         + $6 * EXP(-EXTRACT(EPOCH FROM ($7::timestamptz - last_accessed_at)) / 2592000.0)
+       ) * COALESCE(trust_score, 1.0) AS score,
+       (
+         $4 * (1 - (embedding <=> $1))
+         + CASE WHEN (1 - (embedding <=> $1)) >= $8 THEN (
+           $5 * importance
+           + $6 * EXP(-EXTRACT(EPOCH FROM ($7::timestamptz - last_accessed_at)) / 2592000.0)
+         ) ELSE 0 END
+       ) * COALESCE(trust_score, 1.0) AS ranking_score
+     FROM memories
+     WHERE workspace_id = $2
+       AND deleted_at IS NULL
+       AND expired_at IS NULL
+       AND status = 'active'
+       ${agentClause.sql}
+       ${visibilityClause.sql}
+     ORDER BY ranking_score DESC
+     LIMIT $3`, params);
+    return result.rows.map(normalizeSearchRow);
+}
+/**
+ * Find near-duplicate memories within a workspace scope.
+ * Used during workspace-scoped ingest for AUDN conflict detection.
+ */
+export async function findDuplicateVectorsInWorkspace(pool, workspaceId, embedding, threshold, limit, agentScope = 'all', callerAgentId) {
+    const params = [pgvector.toSql(embedding), workspaceId, threshold, limit];
+    let nextParam = 5;
+    const agentClause = buildAgentScopeClause(agentScope, callerAgentId, params, nextParam);
+    const result = await pool.query(`SELECT id, content, importance, agent_id,
+            1 - (embedding <=> $1) AS similarity
+     FROM memories
+     WHERE workspace_id = $2
+       AND deleted_at IS NULL
+       AND expired_at IS NULL
+       AND status = 'active'
+       AND 1 - (embedding <=> $1) > $3
+       ${agentClause.sql}
+     ORDER BY similarity DESC
+     LIMIT $4`, params);
+    return result.rows;
+}
+/**
+ * Resolve an AgentScope into a SQL WHERE clause fragment.
+ * Returns the SQL string and the count of parameters added.
+ */
+function buildAgentScopeClause(scope, callerAgentId, params, nextParam) {
+    if (scope === 'all')
+        return { sql: '', paramsAdded: 0 };
+    if (scope === 'others') {
+        if (!callerAgentId)
+            return { sql: '', paramsAdded: 0 };
+        params.push(callerAgentId);
+        return { sql: `AND (agent_id IS NULL OR agent_id != $${nextParam})`, paramsAdded: 1 };
+    }
+    if (Array.isArray(scope) && scope.length > 0) {
+        params.push(scope);
+        return { sql: `AND agent_id = ANY($${nextParam}::uuid[])`, paramsAdded: 1 };
+    }
+    const targetId = scope === 'self' ? callerAgentId : scope;
+    if (!targetId)
+        return { sql: '', paramsAdded: 0 };
+    params.push(targetId);
+    return { sql: `AND agent_id = $${nextParam}`, paramsAdded: 1 };
+}
+/**
+ * Build visibility enforcement clause for workspace search.
+ * Ensures agents can only see memories they have access to.
+ */
+function buildVisibilityClauseForSearch(callerAgentId, params, nextParam) {
+    if (!callerAgentId)
+        return { sql: '', paramsAdded: 0 };
+    params.push(callerAgentId);
+    return {
+        sql: `AND (
+      visibility = 'workspace'
+      OR visibility IS NULL
+      OR (visibility = 'agent_only' AND agent_id = $${nextParam})
+      OR (visibility = 'restricted' AND (
+        agent_id = $${nextParam}
+        OR EXISTS (
+          SELECT 1 FROM memory_visibility_grants g
+          WHERE g.memory_id = memories.id AND g.grantee_agent_id = $${nextParam}
+        )
+      ))
+    )`,
+        paramsAdded: 1,
+    };
+}
+async function searchVectorsPg(pool, userId, queryEmbedding, limit, sourceSite, referenceTime) {
+    const { params, siteClause } = buildVectorSearchParams(queryEmbedding, userId, limit, sourceSite, referenceTime);
+    const result = await pool.query(`SELECT *,
+       1 - (embedding <=> $1) AS similarity,
+       1 - (embedding <=> $1) AS semantic_similarity,
+       GREATEST(0, LEAST(1, 1 - (embedding <=> $1))) AS relevance,
+       (
+         $4 * (1 - (embedding <=> $1))
+         + $5 * importance
+         + $6 * EXP(-EXTRACT(EPOCH FROM ($7::timestamptz - last_accessed_at)) / 2592000.0)
+       ) * COALESCE(trust_score, 1.0) AS score,
+       (
+         $4 * (1 - (embedding <=> $1))
+         + CASE WHEN (1 - (embedding <=> $1)) >= $8 THEN (
+           $5 * importance
+           + $6 * EXP(-EXTRACT(EPOCH FROM ($7::timestamptz - last_accessed_at)) / 2592000.0)
+         ) ELSE 0 END
+       ) * COALESCE(trust_score, 1.0) AS ranking_score
+     FROM memories
+     WHERE user_id = $2
+       AND deleted_at IS NULL
+       AND expired_at IS NULL
+       AND status = 'active'
+       AND workspace_id IS NULL
+       ${siteClause}
+     ORDER BY ranking_score DESC
+     LIMIT $3`, params);
+    return result.rows.map(normalizeSearchRow);
+}
+async function findDuplicateVectorsPg(pool, userId, embedding, threshold, limit) {
+    const result = await pool.query(`SELECT id, content, importance, 1 - (embedding <=> $1) AS similarity
+     FROM memories
+     WHERE user_id = $2
+       AND deleted_at IS NULL
+       AND expired_at IS NULL
+       AND status = 'active'
+       AND workspace_id IS NULL
+       AND 1 - (embedding <=> $1) > $3
+     ORDER BY similarity DESC
+     LIMIT $4`, [pgvector.toSql(embedding), userId, threshold, limit]);
+    return result.rows;
+}
+async function searchKeywordPg(pool, userId, queryText, limit, sourceSite) {
+    const siteFilter = sourceSite ? 'AND source_site = $4' : '';
+    const params = [userId, queryText, normalizeLimit(limit)];
+    if (sourceSite)
+        params.push(sourceSite);
+    const result = await pool.query(`SELECT *,
+       LEAST(ts_rank(search_vector, plainto_tsquery('english', $2)), 1.0) AS similarity,
+       LEAST(ts_rank(search_vector, plainto_tsquery('english', $2)), 1.0) AS semantic_similarity,
+       LEAST(ts_rank(search_vector, plainto_tsquery('english', $2)), 1.0) AS relevance,
+       ts_rank(search_vector, plainto_tsquery('english', $2)) AS score,
+       ts_rank(search_vector, plainto_tsquery('english', $2)) AS ranking_score
+     FROM memories
+     WHERE user_id = $1
+       AND deleted_at IS NULL
+       AND expired_at IS NULL
+       AND status = 'active'
+       AND workspace_id IS NULL
+       ${siteFilter}
+       AND search_vector @@ plainto_tsquery('english', $2)
+     ORDER BY ts_rank(search_vector, plainto_tsquery('english', $2)) DESC, importance DESC
+     LIMIT $3`, params);
+    return result.rows.map(normalizeSearchRow);
+}
+async function searchHybridPg(pool, userId, queryText, queryEmbedding, limit, sourceSite, referenceTime) {
+    const { params, siteFilter } = buildHybridSearchParams(queryEmbedding, userId, queryText, limit, 'source_site', sourceSite, referenceTime);
+    const result = await pool.query(`WITH vector_ranked AS (
+       SELECT id, ROW_NUMBER() OVER (ORDER BY embedding <=> $1) AS vrank
+       FROM memories
+       WHERE user_id = $2 AND deleted_at IS NULL AND expired_at IS NULL AND status = 'active' AND workspace_id IS NULL ${siteFilter}
+       ORDER BY embedding <=> $1
+       LIMIT $4 * 4
+     ),
+     fts_ranked AS (
+       SELECT id, ROW_NUMBER() OVER (ORDER BY ts_rank(search_vector, plainto_tsquery('english', $3)) DESC) AS ftsrank
+       FROM memories
+       WHERE user_id = $2 AND deleted_at IS NULL AND expired_at IS NULL AND status = 'active' AND workspace_id IS NULL ${siteFilter}
+         AND search_vector @@ plainto_tsquery('english', $3)
+       ORDER BY ts_rank(search_vector, plainto_tsquery('english', $3)) DESC
+       LIMIT $4 * 4
+     ),
+     fused AS (
+       SELECT COALESCE(v.id, f.id) AS id,
+         COALESCE(1.0 / (${RRF_K} + v.vrank), 0) + COALESCE(1.0 / (${RRF_K} + f.ftsrank), 0) AS rrf_score
+       FROM vector_ranked v
+       FULL OUTER JOIN fts_ranked f ON v.id = f.id
+     )
+     SELECT m.*,
+       1 - (m.embedding <=> $1) AS similarity,
+       1 - (m.embedding <=> $1) AS semantic_similarity,
+       GREATEST(0, LEAST(1, 1 - (m.embedding <=> $1))) AS relevance,
+       (
+         $5 * (1 - (m.embedding <=> $1))
+         + $6 * m.importance
+         + $7 * EXP(-EXTRACT(EPOCH FROM ($8::timestamptz - m.last_accessed_at)) / 2592000.0)
+         + ${config.retrievalProfileSettings.lexicalWeight} * f.rrf_score
+       ) * COALESCE(m.trust_score, 1.0) AS score,
+       (
+         $5 * (1 - (m.embedding <=> $1))
+         + CASE WHEN (1 - (m.embedding <=> $1)) >= $9 THEN (
+           $6 * m.importance
+           + $7 * EXP(-EXTRACT(EPOCH FROM ($8::timestamptz - m.last_accessed_at)) / 2592000.0)
+         ) ELSE 0 END
+         -- Lexical RRF stays outside the semantic boost gate because exact text match is itself a relevance signal.
+         + ${config.retrievalProfileSettings.lexicalWeight} * f.rrf_score
+       ) * COALESCE(m.trust_score, 1.0) AS ranking_score
+     FROM fused f
+     JOIN memories m ON m.id = f.id
+     ORDER BY ranking_score DESC
+     LIMIT $4`, params);
+    return result.rows.map(normalizeSearchRow);
+}
+async function searchVectorsRuvectorMock(pool, userId, queryEmbedding, limit, sourceSite, referenceTime) {
+    const memories = await loadActiveMemories(pool, userId, sourceSite);
+    return rankAndSortMemories(memories, queryEmbedding, limit, referenceTime);
+}
+async function findDuplicateVectorsRuvectorMock(pool, userId, embedding, threshold, limit) {
+    const memories = await loadActiveMemories(pool, userId);
+    return findDuplicatesInMemoryList(memories, embedding, threshold, limit);
+}
+async function searchVectorsZvecMock(pool, userId, queryEmbedding, limit, sourceSite, referenceTime) {
+    const memories = await loadActiveMemories(pool, userId, sourceSite);
+    const shortlist = buildApproximateShortlist(memories, queryEmbedding, limit);
+    return rankAndSortMemories(shortlist, queryEmbedding, limit, referenceTime);
+}
+async function findDuplicateVectorsZvecMock(pool, userId, embedding, threshold, limit) {
+    const memories = await loadActiveMemories(pool, userId);
+    const shortlist = buildApproximateShortlist(memories, embedding, limit * 8);
+    return findDuplicatesInMemoryList(shortlist, embedding, threshold, limit);
+}
+/** Shared in-memory duplicate detection for mock backends. */
+function findDuplicatesInMemoryList(memories, embedding, threshold, limit) {
+    return memories
+        .map((memory) => buildCandidate(memory, embedding))
+        .filter((candidate) => candidate.similarity > threshold)
+        .sort((left, right) => right.similarity - left.similarity)
+        .slice(0, normalizeLimit(limit));
+}
+/** Shared rank-and-sort for mock vector search backends. */
+function rankAndSortMemories(memories, queryEmbedding, limit, referenceTime) {
+    return memories
+        .map((memory) => rankMemory(memory, queryEmbedding, referenceTime))
+        .sort((left, right) => (right.ranking_score ?? right.score) - (left.ranking_score ?? left.score))
+        .slice(0, normalizeLimit(limit));
+}
+async function loadActiveMemories(pool, userId, sourceSite) {
+    const result = await pool.query(`SELECT * FROM memories
+     WHERE user_id = $1
+       AND deleted_at IS NULL
+       AND expired_at IS NULL
+       AND status = 'active'
+       AND workspace_id IS NULL
+       ${sourceSite ? 'AND source_site = $2' : ''}`, sourceSite ? [userId, sourceSite] : [userId]);
+    return result.rows.map(normalizeMemoryRow);
+}
+function rankMemory(memory, queryEmbedding, referenceTime) {
+    const similarity = cosineSimilarity(queryEmbedding, memory.embedding);
+    const rawScore = computeScore(similarity, memory.importance, memory.last_accessed_at, referenceTime, false);
+    const score = rawScore * (memory.trust_score ?? 1.0);
+    const rawRankingScore = computeScore(similarity, memory.importance, memory.last_accessed_at, referenceTime, true);
+    const rankingScore = rawRankingScore * (memory.trust_score ?? 1.0);
+    return {
+        ...memory,
+        similarity,
+        score,
+        semantic_similarity: similarity,
+        ranking_score: rankingScore,
+        relevance: clampUnit(similarity),
+    };
+}
+function buildCandidate(memory, queryEmbedding) {
+    return {
+        id: memory.id,
+        content: memory.content,
+        importance: memory.importance,
+        similarity: cosineSimilarity(queryEmbedding, memory.embedding),
+    };
+}
+function buildApproximateShortlist(memories, queryEmbedding, limit) {
+    const candidatePool = Math.max(normalizeLimit(limit) * 6, 24);
+    return memories
+        .map((memory) => ({
+        memory,
+        similarity: approximateCosineSimilarity(queryEmbedding, memory.embedding),
+    }))
+        .sort((left, right) => right.similarity - left.similarity)
+        .slice(0, candidatePool)
+        .map((entry) => entry.memory);
+}
+function computeScore(similarity, importance, lastAccessedAt, referenceTime, applyRankingFloor) {
+    const refMs = referenceTime ? referenceTime.getTime() : Date.now();
+    const secondsSinceAccess = (refMs - lastAccessedAt.getTime()) / 1000;
+    const recency = Math.exp(-secondsSinceAccess / 2592000.0);
+    const canUseNonSemanticScore = !applyRankingFloor
+        || similarity >= clampUnit(config.retrievalProfileSettings.rankingMinSimilarity);
+    const nonSemanticScore = canUseNonSemanticScore
+        ? (config.scoringWeightImportance * importance) + (config.scoringWeightRecency * recency)
+        : 0;
+    return (config.scoringWeightSimilarity * similarity) + nonSemanticScore;
+}
+function approximateCosineSimilarity(left, right) {
+    return cosineSimilarity(projectEmbedding(left), projectEmbedding(right));
+}
+function projectEmbedding(values) {
+    const projected = [];
+    for (let index = 0; index < values.length; index += 6) {
+        projected.push(values[index]);
+    }
+    return projected;
+}
+function normalizeLimit(limit) {
+    return Math.max(1, Math.min(100, limit));
+}

package/dist/db/repository-wipe.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @file Full-wipe path for the deleteAll (user-scoped + global)
+ * cleanup-then-hard-delete sequence.
+ *
+ * Extracted from `repository-write.ts` to keep that module under
+ * the workspace's 400-non-comment-LOC cap. The wipe path is its own
+ * concern: it cleans managed blobs first (so a failure can mark
+ * surviving rows `raw_storage_failed` + sync the linked artifact)
+ * and then hard-deletes the memory tables, raw_documents,
+ * storage_artifacts, and raw_sources in FK-safe order.
+ */
+import type pg from 'pg';
+import type { RawContentStore } from '../storage/raw-content-store.js';
+import type { RawContentStoreRegistry } from '../storage/store-registry.js';
+export interface DeleteAllOptions {
+    rawContentStore?: RawContentStore | null;
+    /**
+     * Phase 4a per-row dispatch registry. Defaults to a single-store
+     * registry wrapping `rawContentStore` so existing callers that
+     * pass just the active store continue to work; composition-root
+     * code passes a multi-provider registry when
+     * `RAW_STORAGE_LEGACY_PROVIDERS` is set.
+     */
+    storeRegistry?: RawContentStoreRegistry;
+}
+/**
+ * Hard-wipe everything for a user (`userId` set) or globally
+ * (`userId` undefined). Cleanup runs first; on failure the surviving
+ * rows are marked `raw_storage_failed` (with the linked artifact
+ * synced via the paired helper) and `ManagedBlobCleanupError` is
+ * thrown without touching the rest of the tables — the operator
+ * fixes the upstream issue and retries.
+ */
+export declare function deleteAll(pool: pg.Pool, userId?: string, options?: DeleteAllOptions): Promise<void>;

package/dist/db/repository-wipe.js

@@ -0,0 +1,94 @@
+/**
+ * @file Full-wipe path for the deleteAll (user-scoped + global)
+ * cleanup-then-hard-delete sequence.
+ *
+ * Extracted from `repository-write.ts` to keep that module under
+ * the workspace's 400-non-comment-LOC cap. The wipe path is its own
+ * concern: it cleans managed blobs first (so a failure can mark
+ * surviving rows `raw_storage_failed` + sync the linked artifact)
+ * and then hard-deletes the memory tables, raw_documents,
+ * storage_artifacts, and raw_sources in FK-safe order.
+ */
+import { cleanupManagedBlobs, ManagedBlobCleanupError, } from '../storage/cleanup.js';
+import { singleStoreRegistry } from '../storage/store-registry.js';
+import { listManagedBlobsForUser } from './raw-document-blob-repository.js';
+import { buildRawStorageCleanupFailureEnvelope, markCleanupFailedAndSyncArtifact, } from './raw-doc-artifact-sync.js';
+/**
+ * Hard-wipe everything for a user (`userId` set) or globally
+ * (`userId` undefined). Cleanup runs first; on failure the surviving
+ * rows are marked `raw_storage_failed` (with the linked artifact
+ * synced via the paired helper) and `ManagedBlobCleanupError` is
+ * thrown without touching the rest of the tables — the operator
+ * fixes the upstream issue and retries.
+ */
+export async function deleteAll(pool, userId, options = {}) {
+    const blobs = await listManagedBlobsForUser(pool, userId);
+    if (blobs.length > 0) {
+        const registry = options.storeRegistry
+            ?? singleStoreRegistry(options.rawContentStore ?? null);
+        const result = await cleanupManagedBlobs(registry, blobs);
+        if (result.failures.length > 0) {
+            for (const failure of result.failures) {
+                await markDeleteAllCleanupFailure(pool, userId, failure.rawDocumentId, buildRawStorageCleanupFailureEnvelope(failure.message, failure.storageProvider));
+            }
+            throw new ManagedBlobCleanupError(result);
+        }
+    }
+    if (userId)
+        await deleteAllForUser(pool, userId);
+    else
+        await deleteAllGlobal(pool);
+}
+/**
+ * Mark a cleanup-failure row `raw_storage_failed` and sync the
+ * linked artifact to `failed`. For `userId` set (user-scoped wipe),
+ * we use the standard paired helper. For the global wipe path
+ * (`userId` undefined), we resolve the row's owner first so the
+ * paired helper can run with its owner-scope guard intact.
+ */
+async function markDeleteAllCleanupFailure(pool, userId, rawDocumentId, lastError) {
+    if (userId !== undefined) {
+        await markCleanupFailedAndSyncArtifact(pool, { userId, rawDocumentId, lastError });
+        return;
+    }
+    const lookup = await pool.query(`SELECT user_id FROM raw_documents WHERE id = $1`, [rawDocumentId]);
+    if (lookup.rowCount === 0)
+        return;
+    await markCleanupFailedAndSyncArtifact(pool, {
+        userId: lookup.rows[0].user_id,
+        rawDocumentId,
+        lastError,
+    });
+}
+/**
+ * User-scoped hard-delete. Chunks → documents → storage_artifacts →
+ * sources, in FK-safe order. `storage_artifacts` is hard-deleted
+ * AFTER `raw_documents` because the composite FK
+ * `raw_documents(storage_artifact_id, user_id) → storage_artifacts`
+ * points one way.
+ */
+async function deleteAllForUser(pool, userId) {
+    await pool.query('DELETE FROM memory_evidence WHERE claim_version_id IN (SELECT id FROM memory_claim_versions WHERE user_id = $1)', [userId]);
+    await pool.query('DELETE FROM memory_claim_versions WHERE user_id = $1', [userId]);
+    await pool.query('DELETE FROM memory_claims WHERE user_id = $1', [userId]);
+    await pool.query('DELETE FROM memory_links WHERE source_id IN (SELECT id FROM memories WHERE user_id = $1)', [userId]);
+    await pool.query('DELETE FROM memories WHERE user_id = $1', [userId]);
+    await pool.query('DELETE FROM episodes WHERE user_id = $1', [userId]);
+    await pool.query('DELETE FROM document_chunks WHERE user_id = $1', [userId]);
+    await pool.query('DELETE FROM raw_documents WHERE user_id = $1', [userId]);
+    await pool.query('DELETE FROM storage_artifacts WHERE user_id = $1', [userId]);
+    await pool.query('DELETE FROM raw_sources WHERE user_id = $1', [userId]);
+}
+/** Global hard-delete. Same FK-safe order; no user filter. */
+async function deleteAllGlobal(pool) {
+    await pool.query('DELETE FROM memory_evidence');
+    await pool.query('DELETE FROM memory_claim_versions');
+    await pool.query('DELETE FROM memory_claims');
+    await pool.query('DELETE FROM memory_links');
+    await pool.query('DELETE FROM memories');
+    await pool.query('DELETE FROM episodes');
+    await pool.query('DELETE FROM document_chunks');
+    await pool.query('DELETE FROM raw_documents');
+    await pool.query('DELETE FROM storage_artifacts');
+    await pool.query('DELETE FROM raw_sources');
+}

package/dist/db/repository-write.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Write-side queries for episodes and active memory projections.
+ */
+import pg from 'pg';
+import { type CanonicalFactPayload, type CanonicalMemoryObjectFamily, type CanonicalMemoryObjectLineage, type CanonicalMemoryObjectProvenance, type MemoryMetadata, type StoreMemoryInput } from './repository-types.js';
+export interface StoreEpisodeInput {
+    userId: string;
+    content: string;
+    sourceSite: string;
+    sourceUrl?: string;
+    sessionId?: string;
+    workspaceId?: string;
+    agentId?: string;
+}
+export declare function storeEpisode(pool: pg.Pool, input: StoreEpisodeInput): Promise<string>;
+export declare function storeEpisodeWithClient(client: pg.PoolClient, input: StoreEpisodeInput): Promise<string>;
+export type { StoreMemoryInput };
+export interface StoreCanonicalMemoryObjectInput {
+    userId: string;
+    objectFamily: CanonicalMemoryObjectFamily;
+    payloadFormat?: string;
+    canonicalPayload: CanonicalFactPayload;
+    provenance: CanonicalMemoryObjectProvenance;
+    observedAt?: Date;
+    lineage: CanonicalMemoryObjectLineage;
+}
+export declare function storeCanonicalMemoryObject(pool: pg.Pool, input: StoreCanonicalMemoryObjectInput): Promise<string>;
+export declare function storeMemory(pool: pg.Pool, input: StoreMemoryInput): Promise<string>;
+export declare function storeMemoryWithClient(client: pg.PoolClient, input: StoreMemoryInput): Promise<string>;
+export declare function updateMemoryContent(pool: pg.Pool, userId: string, id: string, content: string, embedding: number[], importance: number, keywords?: string, trustScore?: number): Promise<void>;
+export declare function updateMemoryContentWithClient(client: pg.PoolClient, userId: string, id: string, content: string, embedding: number[], importance: number, keywords?: string, trustScore?: number): Promise<void>;
+export declare function updateMemoryMetadata(pool: pg.Pool, userId: string, id: string, metadata: MemoryMetadata): Promise<void>;
+/**
+ * Set the topic_abstraction + topic_embedding columns on a batch of memories.
+ * Used by the post-write topic-abstraction processor (Sprint 3 EO experiment).
+ *
+ * One UPDATE per call; the caller batches by chunk so all facts from a chunk
+ * receive the same topic.
+ */
+export declare function updateMemoryTopicAbstraction(pool: pg.Pool, userId: string, memoryIds: string[], topic: string, topicEmbedding: number[]): Promise<void>;
+export declare function softDeleteMemory(pool: pg.Pool, userId: string, id: string): Promise<void>;
+export declare function softDeleteMemoryWithClient(client: pg.PoolClient, userId: string, id: string): Promise<void>;
+export declare function softDeleteMemoryInWorkspace(pool: pg.Pool, id: string, workspaceId: string): Promise<void>;
+/**
+ * Soft-delete every memory whose Phase 2 provenance points at the given
+ * `raw_document_id`. The Phase 2 indexer's re-chunk path calls this so
+ * stale derived memories disappear from `/v1/memories/search` before the
+ * fresh generation lands.
+ */
+export declare function softDeleteMemoriesForDocument(q: pg.Pool | pg.PoolClient, userId: string, rawDocumentId: string): Promise<number>;
+/**
+ * Mark a memory as temporally expired (contradicted/superseded).
+ * Unlike soft-delete, expired memories are preserved for temporal queries:
+ * "what did I know as of date X?" can still retrieve them.
+ */
+export declare function expireMemory(pool: pg.Pool, userId: string, id: string): Promise<void>;
+export declare function expireMemoryWithClient(client: pg.PoolClient, userId: string, id: string): Promise<void>;
+export declare function touchMemory(pool: pg.Pool, id: string): Promise<void>;
+export declare function updateOpinionConfidence(pool: pg.Pool, userId: string, memoryId: string, newConfidence: number): Promise<void>;
+export declare function backdateMemories(pool: pg.Pool, ids: string[], timestamp: Date): Promise<void>;
+export { deleteAll } from './repository-wipe.js';