@atomicmemory/core 1.0.0

package/dist/db/repository-document-delete.js

@@ -0,0 +1,156 @@
+/**
+ * @file Document-scoped delete cascades.
+ *
+ * Owns `softDeleteDocumentCascade` (single-document) and
+ * `deleteBySource` (source-reset), plus the Step-7 helpers that
+ * soft-delete linked `storage_artifacts` rows in the same
+ * transaction. Extracted from `repository-write.ts` to keep that
+ * module under the workspace 400-non-comment-LOC cap.
+ */
+import { deleteDocumentsBySourceWithClient, softDeleteRawDocument, } from './raw-document-repository.js';
+import { deleteChunksBySourceWithClient, softDeleteChunksForDocument } from './document-chunk-repository.js';
+import { listManagedBlobsBySourceWithClient, listManagedBlobsForDocumentWithClient, } from './raw-document-blob-repository.js';
+import { softDeleteMemoriesForDocument } from './repository-write.js';
+/**
+ * Soft-delete a document together with the chunks + provenance-linked
+ * memories materialized from it (Phase 2). Runs in one transaction
+ * with a per-document advisory lock so a concurrent index call
+ * serializes cleanly. Idempotent: returns `{ removed: false }` when
+ * the document was already missing/deleted/owned by a different user.
+ *
+ * Step 7 — when the document has no managed blob to clean up
+ * (pointer-only, or already-terminal managed), the linked
+ * `storage_artifacts` row is soft-deleted in the same transaction.
+ * The cleanup path handles the managed case via the paired
+ * `markCleanupSuccessAndSyncArtifact` helper.
+ */
+export async function softDeleteDocumentCascade(pool, userId, documentId) {
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN');
+        await client.query('SELECT pg_advisory_xact_lock(hashtext($1))', [documentId]);
+        const blobs = await listManagedBlobsForDocumentWithClient(client, userId, documentId);
+        const memoriesDeleted = await softDeleteMemoriesForDocument(client, userId, documentId);
+        const chunksDeleted = await softDeleteChunksForDocument(client, userId, documentId);
+        const removed = await softDeleteRawDocument(client, userId, documentId);
+        if (removed && blobs.length === 0) {
+            await softDeleteLinkedArtifactForDocumentWithClient(client, userId, documentId);
+        }
+        await client.query('COMMIT');
+        return { removed, memoriesDeleted, chunksDeleted, blobs: removed ? blobs : [] };
+    }
+    catch (err) {
+        await client.query('ROLLBACK').catch(() => undefined);
+        throw err;
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * Soft-delete the `storage_artifacts` row linked to a document
+ * inside an open transaction. No-op when the document has no link.
+ * Owner-scoped on the document side; the artifact's composite FK
+ * to `(id, user_id)` already prevents cross-user pairings.
+ *
+ * Skips rows whose delete lifecycle has already started
+ * (`status IN ('deleting', 'deleted', 'delete_failed')`). After the
+ * Commit D reorder, `StorageService.deleteArtifact` claims the
+ * artifact BEFORE cascading documents — so when this helper runs
+ * during a `policy=with_documents` cascade, the artifact is
+ * already at `status='deleting'` and the storage service's own
+ * finalize step owns the terminal transition. Clobbering the
+ * status here would race the finalize CAS and surface
+ * `markDeleteSuccess: no matching claim`.
+ */
+async function softDeleteLinkedArtifactForDocumentWithClient(client, userId, documentId) {
+    await client.query(`UPDATE storage_artifacts sa
+       SET status = 'deleted',
+           deleted_at = COALESCE(sa.deleted_at, NOW()),
+           delete_attempt_id = NULL,
+           updated_at = NOW()
+      FROM raw_documents rd
+      WHERE rd.id = $1
+        AND rd.user_id = $2
+        AND rd.storage_artifact_id = sa.id
+        AND sa.status NOT IN ('deleting', 'deleted', 'delete_failed')`, [documentId, userId]);
+}
+/**
+ * Source-reset variant — soft-deletes any pointer (or already-
+ * clean managed) artifact linked to a document under the given
+ * source. Managed-blob rows that still need cleanup are left to
+ * the post-commit cleanup path.
+ *
+ * Skips rows whose delete lifecycle has already started
+ * (`status IN ('deleting', 'deleted', 'delete_failed')`). Without
+ * this guard a source reset racing `StorageService.deleteArtifact`
+ * could clobber the artifact's claimed `delete_attempt_id`, causing
+ * the storage service's finalize CAS to miss after `backend.delete`
+ * runs. Mirrors the same guard on
+ * `softDeleteLinkedArtifactForDocumentWithClient`.
+ */
+async function softDeleteLinkedArtifactsForSourceWithClient(client, userId, sourceSite) {
+    await client.query(`UPDATE storage_artifacts sa
+       SET status = 'deleted',
+           deleted_at = COALESCE(sa.deleted_at, NOW()),
+           delete_attempt_id = NULL,
+           updated_at = NOW()
+      FROM raw_documents rd
+      JOIN raw_sources rs ON rs.id = rd.raw_source_id
+     WHERE rs.user_id = $1
+       AND rs.source_site = $2
+       AND rd.user_id = $1
+       AND rd.storage_artifact_id = sa.id
+       AND sa.status NOT IN ('deleting', 'deleted', 'delete_failed')
+       AND (rd.storage_uri IS NULL OR rd.raw_storage_status IN ('blob_deleted', 'blob_tombstoned'))`, [userId, sourceSite]);
+}
+/**
+ * Delete all data for a given user + source_site combination.
+ * Hard-deletes across memory-side tables and soft-deletes
+ * (tombstones) matching `raw_documents` in safe referential order
+ * within a single transaction. Step 7 — soft-deletes the linked
+ * `storage_artifacts` rows for pointer-only / terminal-managed
+ * docs in the same transaction, so a source reset cannot leave
+ * orphan active artifact links.
+ */
+export async function deleteBySource(pool, userId, sourceSite) {
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN');
+        await client.query(`DELETE FROM memory_evidence
+       WHERE claim_version_id IN (
+         SELECT id FROM memory_claim_versions WHERE user_id = $1 AND source_site = $2
+       )`, [userId, sourceSite]);
+        await client.query(`DELETE FROM memory_claim_versions WHERE user_id = $1 AND source_site = $2`, [userId, sourceSite]);
+        await client.query(`DELETE FROM memory_claims
+       WHERE user_id = $1
+         AND id NOT IN (SELECT claim_id FROM memory_claim_versions WHERE user_id = $1)`, [userId]);
+        await client.query(`DELETE FROM memory_links
+       WHERE source_id IN (SELECT id FROM memories WHERE user_id = $1 AND source_site = $2 AND workspace_id IS NULL)
+          OR target_id IN (SELECT id FROM memories WHERE user_id = $1 AND source_site = $2 AND workspace_id IS NULL)`, [userId, sourceSite]);
+        await client.query(`DELETE FROM memory_entities
+       WHERE memory_id IN (SELECT id FROM memories WHERE user_id = $1 AND source_site = $2 AND workspace_id IS NULL)`, [userId, sourceSite]);
+        await client.query(`DELETE FROM memory_atomic_facts WHERE user_id = $1 AND source_site = $2
+       AND parent_memory_id IN (SELECT id FROM memories WHERE user_id = $1 AND source_site = $2 AND workspace_id IS NULL)`, [userId, sourceSite]);
+        const memResult = await client.query(`DELETE FROM memories WHERE user_id = $1 AND source_site = $2 AND workspace_id IS NULL RETURNING id`, [userId, sourceSite]);
+        const epResult = await client.query(`DELETE FROM episodes WHERE user_id = $1 AND source_site = $2 RETURNING id`, [userId, sourceSite]);
+        const blobs = await listManagedBlobsBySourceWithClient(client, userId, sourceSite);
+        await deleteChunksBySourceWithClient(client, userId, sourceSite);
+        const deletedDocuments = await deleteDocumentsBySourceWithClient(client, userId, sourceSite);
+        await softDeleteLinkedArtifactsForSourceWithClient(client, userId, sourceSite);
+        await client.query('COMMIT');
+        return {
+            deletedMemories: memResult.rowCount ?? 0,
+            deletedEpisodes: epResult.rowCount ?? 0,
+            deletedDocuments,
+            blobs,
+        };
+    }
+    catch (err) {
+        await client.query('ROLLBACK');
+        throw err;
+    }
+    finally {
+        client.release();
+    }
+}

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

@@ -0,0 +1,114 @@
+/**
+ * Entity graph repository — stores structured entities extracted from memories,
+ * handles entity resolution (dedup by embedding similarity + type match), and
+ * provides entity-aware retrieval expansion for multi-hop queries.
+ */
+import pg from 'pg';
+import { type EntityRow, type EntityRelationRow, type EntityType, type RelationType } from './repository-types.js';
+export interface EntityInput {
+    userId: string;
+    name: string;
+    entityType: EntityType;
+    embedding: number[];
+    aliasNames?: string[];
+}
+export declare class EntityRepository {
+    private pool;
+    constructor(pool: pg.Pool);
+    /**
+     * Shared implementation: run a distinct-ID query and filter out excluded IDs.
+     * Both findMemoryIdsByEntities and findRelatedEntityIds delegate here.
+     */
+    private findRelatedIdsExcluding;
+    /**
+     * Resolve-or-create: find an existing entity with the same type and embedding
+     * similarity above threshold, or create a new one. Returns the entity ID.
+     */
+    resolveEntity(input: EntityInput): Promise<string>;
+    resolveEntityWithClient(client: pg.PoolClient, input: EntityInput): Promise<string>;
+    findDeterministicEntity(userId: string, entityType: EntityType, name: string, client?: pg.PoolClient | pg.Pool): Promise<EntityRow | null>;
+    /**
+     * Find the most similar entity of the same type above the resolution threshold.
+     */
+    findSimilarEntity(client: pg.PoolClient | pg.Pool, userId: string, entityType: EntityType, embedding: number[]): Promise<EntityRow | null>;
+    /**
+     * Create a new entity record.
+     */
+    createEntity(client: pg.PoolClient | pg.Pool, input: EntityInput): Promise<string>;
+    /**
+     * Add a name alias to an existing entity if not already present.
+     */
+    mergeAlias(client: pg.PoolClient | pg.Pool, entityId: string, alias: string): Promise<void>;
+    /**
+     * Link a memory to an entity.
+     */
+    linkMemoryToEntity(memoryId: string, entityId: string): Promise<void>;
+    /**
+     * Find all memory IDs linked to a set of entity IDs. Returns unique IDs
+     * excluding any in the exclude set.
+     */
+    findMemoryIdsByEntities(userId: string, entityIds: string[], excludeIds: Set<string>, limit: number): Promise<string[]>;
+    /**
+     * Find entities by exact or substring name match (case-insensitive).
+     * Used for co-retrieval when a query mentions a known entity by name.
+     */
+    findEntitiesByName(userId: string, name: string, limit?: number): Promise<EntityRow[]>;
+    /**
+     * Find entities matching a query embedding (for query-time entity extraction).
+     */
+    searchEntities(userId: string, queryEmbedding: number[], limit: number, minSimilarity?: number): Promise<Array<EntityRow & {
+        similarity: number;
+    }>>;
+    /**
+     * Get all entities linked to a specific memory.
+     */
+    getEntitiesForMemory(memoryId: string): Promise<EntityRow[]>;
+    /**
+     * Get an entity by ID.
+     */
+    getEntity(id: string): Promise<EntityRow | null>;
+    /**
+     * Count entities for a user.
+     */
+    countEntities(userId: string): Promise<number>;
+    /**
+     * Create or update a relation between two entities. Upserts on the
+     * (source, target, type) unique constraint, updating confidence if higher.
+     */
+    upsertRelation(input: {
+        userId: string;
+        sourceEntityId: string;
+        targetEntityId: string;
+        relationType: RelationType;
+        sourceMemoryId?: string;
+        confidence?: number;
+    }): Promise<string>;
+    /**
+     * Find all entities related to a set of entity IDs (1-hop traversal).
+     * Follows relations in both directions to find connected entities.
+     */
+    findRelatedEntityIds(userId: string, entityIds: string[], excludeIds: Set<string>, limit: number): Promise<string[]>;
+    /**
+     * Get all relations for an entity (both directions).
+     */
+    getRelationsForEntity(entityId: string): Promise<EntityRelationRow[]>;
+    /**
+     * Get active relations supported by the entities linked to a specific memory.
+     * This follows the linked entity set instead of relying solely on the first
+     * source_memory_id, so current claims can still recover a slot even when the
+     * same relation was first observed in an older memory.
+     */
+    getRelationsForMemory(userId: string, memoryId: string): Promise<EntityRelationRow[]>;
+    /**
+     * Invalidate a relation by setting valid_to.
+     */
+    invalidateRelation(relationId: string, validTo?: Date): Promise<void>;
+    /**
+     * Count active relations for a user.
+     */
+    countRelations(userId: string): Promise<number>;
+    /**
+     * Delete all entities, relations, and memory_entities for a user or all users.
+     */
+    deleteAll(userId?: string): Promise<void>;
+}

package/dist/db/repository-entities.js

@@ -0,0 +1,317 @@
+/**
+ * Entity graph repository — stores structured entities extracted from memories,
+ * handles entity resolution (dedup by embedding similarity + type match), and
+ * provides entity-aware retrieval expansion for multi-hop queries.
+ */
+import pgvector from 'pgvector/pg';
+import { config } from '../config.js';
+import { normalizeEntityRow, } from './repository-types.js';
+/** Threshold above which two entities with the same type are considered duplicates. */
+const ENTITY_RESOLUTION_THRESHOLD = config.entityResolutionThreshold;
+/**
+ * Normalize entity names for deterministic canonicalization before embedding
+ * similarity is consulted. This is intentionally conservative: punctuation and
+ * spacing differences collapse, but semantic rewrites do not.
+ */
+/** Extract IDs from query rows and filter out excluded ones. */
+function filterExcludedIds(rows, idField, excludeIds) {
+    return rows
+        .map((r) => r[idField])
+        .filter((id) => !excludeIds.has(id));
+}
+/**
+ * Run a query that returns distinct IDs from a join, then exclude already-seen IDs.
+ * Shared by findMemoryIdsByEntities and findRelatedEntityIds.
+ */
+async function queryDistinctIdsWithExclusion(pool, sql, params, idField, excludeIds) {
+    const result = await pool.query(sql, params);
+    return filterExcludedIds(result.rows, idField, excludeIds);
+}
+function normalizeEntityName(name) {
+    const normalized = name
+        .normalize('NFKD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9+#]+/g, ' ')
+        .trim()
+        .replace(/\s+/g, ' ');
+    return normalized || name.trim().toLowerCase();
+}
+export class EntityRepository {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    /**
+     * Shared implementation: run a distinct-ID query and filter out excluded IDs.
+     * Both findMemoryIdsByEntities and findRelatedEntityIds delegate here.
+     */
+    async findRelatedIdsExcluding(sql, idField, userId, entityIds, excludeIds, limit) {
+        if (entityIds.length === 0)
+            return [];
+        return queryDistinctIdsWithExclusion(this.pool, sql, [userId, entityIds, limit], idField, excludeIds);
+    }
+    /**
+     * Resolve-or-create: find an existing entity with the same type and embedding
+     * similarity above threshold, or create a new one. Returns the entity ID.
+     */
+    async resolveEntity(input) {
+        return this.resolveEntityWithClient(this.pool, input);
+    }
+    async resolveEntityWithClient(client, input) {
+        const deterministicMatch = await this.findDeterministicEntity(input.userId, input.entityType, input.name, client);
+        if (deterministicMatch) {
+            await this.mergeAlias(client, deterministicMatch.id, input.name);
+            return deterministicMatch.id;
+        }
+        const match = await this.findSimilarEntity(client, input.userId, input.entityType, input.embedding);
+        if (match) {
+            await this.mergeAlias(client, match.id, input.name);
+            return match.id;
+        }
+        return this.createEntity(client, input);
+    }
+    async findDeterministicEntity(userId, entityType, name, client = this.pool) {
+        const normalizedName = normalizeEntityName(name);
+        const result = await client.query(`SELECT *
+       FROM entities
+       WHERE user_id = $1
+         AND entity_type = $2
+         AND (
+           normalized_name = $3
+           OR $3 = ANY(normalized_alias_names)
+         )
+       ORDER BY created_at ASC
+       LIMIT 1`, [userId, entityType, normalizedName]);
+        return result.rows[0] ? normalizeEntityRow(result.rows[0]) : null;
+    }
+    /**
+     * Find the most similar entity of the same type above the resolution threshold.
+     */
+    async findSimilarEntity(client, userId, entityType, embedding) {
+        const result = await client.query(`SELECT *, 1 - (embedding <=> $1) AS similarity
+       FROM entities
+       WHERE user_id = $2 AND entity_type = $3
+         AND 1 - (embedding <=> $1) >= $4
+       ORDER BY similarity DESC
+       LIMIT 1`, [pgvector.toSql(embedding), userId, entityType, ENTITY_RESOLUTION_THRESHOLD]);
+        return result.rows[0] ? normalizeEntityRow(result.rows[0]) : null;
+    }
+    /**
+     * Create a new entity record.
+     */
+    async createEntity(client, input) {
+        const normalizedName = normalizeEntityName(input.name);
+        const aliasNames = [...new Set((input.aliasNames ?? []).filter((alias) => alias !== input.name))];
+        const normalizedAliasNames = [...new Set(aliasNames
+                .map(normalizeEntityName)
+                .filter((alias) => Boolean(alias) && alias !== normalizedName))];
+        const result = await client.query(`INSERT INTO entities (
+         user_id, name, normalized_name, entity_type, embedding, alias_names, normalized_alias_names
+       )
+       VALUES ($1, $2, $3, $4, $5, $6, $7) RETURNING id`, [
+            input.userId,
+            input.name,
+            normalizedName,
+            input.entityType,
+            pgvector.toSql(input.embedding),
+            aliasNames,
+            normalizedAliasNames,
+        ]);
+        return result.rows[0].id;
+    }
+    /**
+     * Add a name alias to an existing entity if not already present.
+     */
+    async mergeAlias(client, entityId, alias) {
+        const normalizedAlias = normalizeEntityName(alias);
+        await client.query(`UPDATE entities
+       SET alias_names = CASE
+         WHEN $2 = ANY(alias_names) OR lower($2) = lower(name) OR $3 = ANY(normalized_alias_names) THEN alias_names
+         ELSE array_append(alias_names, $2)
+       END,
+       normalized_alias_names = CASE
+         WHEN $3 = normalized_name OR $3 = ANY(normalized_alias_names) THEN normalized_alias_names
+         ELSE array_append(normalized_alias_names, $3)
+       END,
+       updated_at = NOW()
+       WHERE id = $1`, [entityId, alias, normalizedAlias]);
+    }
+    /**
+     * Link a memory to an entity.
+     */
+    async linkMemoryToEntity(memoryId, entityId) {
+        await this.pool.query(`INSERT INTO memory_entities (memory_id, entity_id)
+       VALUES ($1, $2)
+       ON CONFLICT DO NOTHING`, [memoryId, entityId]);
+    }
+    /**
+     * Find all memory IDs linked to a set of entity IDs. Returns unique IDs
+     * excluding any in the exclude set.
+     */
+    async findMemoryIdsByEntities(userId, entityIds, excludeIds, limit) {
+        return this.findRelatedIdsExcluding(`SELECT DISTINCT me.memory_id
+       FROM memory_entities me
+       JOIN memories m ON m.id = me.memory_id AND m.deleted_at IS NULL AND m.expired_at IS NULL AND m.workspace_id IS NULL
+       JOIN entities e ON e.id = me.entity_id
+       WHERE e.user_id = $1
+         AND m.user_id = $1
+         AND me.entity_id = ANY($2)
+       LIMIT $3`, 'memory_id', userId, entityIds, excludeIds, limit);
+    }
+    /**
+     * Find entities by exact or substring name match (case-insensitive).
+     * Used for co-retrieval when a query mentions a known entity by name.
+     */
+    async findEntitiesByName(userId, name, limit = 10) {
+        const normalizedName = normalizeEntityName(name);
+        const result = await this.pool.query(`SELECT * FROM entities
+       WHERE user_id = $1
+         AND (
+           normalized_name = $2
+           OR $2 = ANY(normalized_alias_names)
+         )
+       ORDER BY created_at ASC
+       LIMIT $3`, [userId, normalizedName, limit]);
+        return result.rows.map(normalizeEntityRow);
+    }
+    /**
+     * Find entities matching a query embedding (for query-time entity extraction).
+     */
+    async searchEntities(userId, queryEmbedding, limit, minSimilarity = 0.7) {
+        const result = await this.pool.query(`SELECT *, 1 - (embedding <=> $1) AS similarity
+       FROM entities
+       WHERE user_id = $2
+         AND 1 - (embedding <=> $1) >= $4
+       ORDER BY similarity DESC
+       LIMIT $3`, [pgvector.toSql(queryEmbedding), userId, limit, minSimilarity]);
+        return result.rows.map((row) => ({
+            ...normalizeEntityRow(row),
+            similarity: row.similarity,
+        }));
+    }
+    /**
+     * Get all entities linked to a specific memory.
+     */
+    async getEntitiesForMemory(memoryId) {
+        const result = await this.pool.query(`SELECT e.* FROM entities e
+       JOIN memory_entities me ON me.entity_id = e.id
+       WHERE me.memory_id = $1`, [memoryId]);
+        return result.rows.map(normalizeEntityRow);
+    }
+    /**
+     * Get an entity by ID.
+     */
+    async getEntity(id) {
+        const result = await this.pool.query(`SELECT * FROM entities WHERE id = $1`, [id]);
+        return result.rows[0] ? normalizeEntityRow(result.rows[0]) : null;
+    }
+    /**
+     * Count entities for a user.
+     */
+    async countEntities(userId) {
+        const result = await this.pool.query(`SELECT COUNT(*)::int AS count FROM entities WHERE user_id = $1`, [userId]);
+        return result.rows[0].count;
+    }
+    // ─── Relations ───────────────────────────────────────────────────────
+    /**
+     * Create or update a relation between two entities. Upserts on the
+     * (source, target, type) unique constraint, updating confidence if higher.
+     */
+    async upsertRelation(input) {
+        const result = await this.pool.query(`INSERT INTO entity_relations
+         (user_id, source_entity_id, target_entity_id, relation_type, source_memory_id, confidence)
+       VALUES ($1, $2, $3, $4, $5, $6)
+       ON CONFLICT (source_entity_id, target_entity_id, relation_type)
+       DO UPDATE SET
+         confidence = GREATEST(entity_relations.confidence, EXCLUDED.confidence),
+         source_memory_id = EXCLUDED.source_memory_id
+       RETURNING id`, [
+            input.userId,
+            input.sourceEntityId,
+            input.targetEntityId,
+            input.relationType,
+            input.sourceMemoryId ?? null,
+            input.confidence ?? 1.0,
+        ]);
+        return result.rows[0].id;
+    }
+    /**
+     * Find all entities related to a set of entity IDs (1-hop traversal).
+     * Follows relations in both directions to find connected entities.
+     */
+    async findRelatedEntityIds(userId, entityIds, excludeIds, limit) {
+        return this.findRelatedIdsExcluding(`SELECT DISTINCT entity_id FROM (
+         SELECT target_entity_id AS entity_id
+         FROM entity_relations
+         WHERE user_id = $1 AND source_entity_id = ANY($2) AND valid_to IS NULL
+         UNION
+         SELECT source_entity_id AS entity_id
+         FROM entity_relations
+         WHERE user_id = $1 AND target_entity_id = ANY($2) AND valid_to IS NULL
+       ) AS related
+       LIMIT $3`, 'entity_id', userId, entityIds, excludeIds, limit);
+    }
+    /**
+     * Get all relations for an entity (both directions).
+     */
+    async getRelationsForEntity(entityId) {
+        const result = await this.pool.query(`SELECT * FROM entity_relations
+       WHERE (source_entity_id = $1 OR target_entity_id = $1)
+         AND valid_to IS NULL
+       ORDER BY created_at DESC`, [entityId]);
+        return result.rows;
+    }
+    /**
+     * Get active relations supported by the entities linked to a specific memory.
+     * This follows the linked entity set instead of relying solely on the first
+     * source_memory_id, so current claims can still recover a slot even when the
+     * same relation was first observed in an older memory.
+     */
+    async getRelationsForMemory(userId, memoryId) {
+        const result = await this.pool.query(`SELECT er.*
+       FROM entity_relations er
+       JOIN memory_entities me_source
+         ON me_source.entity_id = er.source_entity_id
+        AND me_source.memory_id = $2
+       JOIN memory_entities me_target
+         ON me_target.entity_id = er.target_entity_id
+        AND me_target.memory_id = $2
+       WHERE er.user_id = $1
+         AND valid_to IS NULL
+       ORDER BY (er.source_memory_id = $2) DESC,
+                er.relation_type ASC,
+                er.source_entity_id ASC,
+                er.target_entity_id ASC`, [userId, memoryId]);
+        return result.rows;
+    }
+    /**
+     * Invalidate a relation by setting valid_to.
+     */
+    async invalidateRelation(relationId, validTo = new Date()) {
+        await this.pool.query(`UPDATE entity_relations SET valid_to = $1 WHERE id = $2`, [validTo, relationId]);
+    }
+    /**
+     * Count active relations for a user.
+     */
+    async countRelations(userId) {
+        const result = await this.pool.query(`SELECT COUNT(*)::int AS count FROM entity_relations
+       WHERE user_id = $1 AND valid_to IS NULL`, [userId]);
+        return result.rows[0].count;
+    }
+    /**
+     * Delete all entities, relations, and memory_entities for a user or all users.
+     */
+    async deleteAll(userId) {
+        if (userId) {
+            await this.pool.query(`DELETE FROM entity_relations WHERE user_id = $1`, [userId]);
+            await this.pool.query(`DELETE FROM memory_entities WHERE entity_id IN (SELECT id FROM entities WHERE user_id = $1)`, [userId]);
+            await this.pool.query(`DELETE FROM entities WHERE user_id = $1`, [userId]);
+        }
+        else {
+            await this.pool.query(`DELETE FROM entity_relations`);
+            await this.pool.query(`DELETE FROM memory_entities`);
+            await this.pool.query(`DELETE FROM entities`);
+        }
+    }
+}

package/dist/db/repository-entity-attributes.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Repository for the entity_attributes table (EAI — Sprint 4).
+ *
+ * Stores (entity, attribute, value) triples. Read path: look up triples
+ * for a user by entity_name (fuzzy/lowercase) and/or attribute_key.
+ * Write path: bulk insert from the extractor service.
+ */
+import type pg from 'pg';
+export type ValueType = 'number' | 'string' | 'list' | 'boolean' | 'date';
+export interface EntityAttributeRow {
+    id: string;
+    user_id: string;
+    entity_name: string;
+    attribute_key: string;
+    attribute_value: string;
+    value_type: ValueType;
+    source_memory_id: string | null;
+    observed_at: Date;
+    created_at: Date;
+}
+export interface EntityAttributeInput {
+    userId: string;
+    entityName: string;
+    attributeKey: string;
+    attributeValue: string;
+    valueType: ValueType;
+    sourceMemoryId?: string | null;
+    observedAt?: Date | null;
+}
+export declare class EntityAttributesRepository {
+    private readonly pool;
+    constructor(pool: pg.Pool);
+    bulkInsert(rows: EntityAttributeInput[]): Promise<number>;
+    /** Lookup attributes by entity name (case-insensitive). Returns most-recent first. */
+    findByEntity(userId: string, entityName: string, limit?: number): Promise<EntityAttributeRow[]>;
+    /** Lookup attributes by attribute key (case-insensitive). Useful for "how many X" queries. */
+    findByAttribute(userId: string, attributeKey: string, limit?: number): Promise<EntityAttributeRow[]>;
+    /** Combined lookup: entity OR attribute matches; useful when query mentions both. */
+    findByEntityOrAttribute(userId: string, tokens: string[], limit?: number): Promise<EntityAttributeRow[]>;
+    deleteAllForUser(userId: string): Promise<number>;
+}