@atomicmemory/core 1.0.0

package/dist/db/repository-entity-attributes.js

@@ -0,0 +1,65 @@
+export class EntityAttributesRepository {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async bulkInsert(rows) {
+        if (rows.length === 0)
+            return 0;
+        const values = [];
+        const placeholders = [];
+        rows.forEach((r, i) => {
+            const base = i * 7;
+            placeholders.push(`($${base + 1},$${base + 2},$${base + 3},$${base + 4},$${base + 5},$${base + 6},$${base + 7})`);
+            values.push(r.userId, r.entityName, r.attributeKey, r.attributeValue, r.valueType, r.sourceMemoryId ?? null, r.observedAt ?? new Date());
+        });
+        const sql = 'INSERT INTO entity_attributes (user_id, entity_name, attribute_key, attribute_value, value_type, source_memory_id, observed_at) VALUES ' +
+            placeholders.join(',');
+        const result = await this.pool.query(sql, values);
+        return result.rowCount ?? 0;
+    }
+    /** Lookup attributes by entity name (case-insensitive). Returns most-recent first. */
+    async findByEntity(userId, entityName, limit = 20) {
+        const result = await this.pool.query(`SELECT id, user_id, entity_name, attribute_key, attribute_value, value_type,
+              source_memory_id, observed_at, created_at
+       FROM entity_attributes
+       WHERE user_id = $1 AND lower(entity_name) = lower($2)
+       ORDER BY observed_at DESC
+       LIMIT $3`, [userId, entityName, limit]);
+        return result.rows;
+    }
+    /** Lookup attributes by attribute key (case-insensitive). Useful for "how many X" queries. */
+    async findByAttribute(userId, attributeKey, limit = 20) {
+        const result = await this.pool.query(`SELECT id, user_id, entity_name, attribute_key, attribute_value, value_type,
+              source_memory_id, observed_at, created_at
+       FROM entity_attributes
+       WHERE user_id = $1 AND lower(attribute_key) = lower($2)
+       ORDER BY observed_at DESC
+       LIMIT $3`, [userId, attributeKey, limit]);
+        return result.rows;
+    }
+    /** Combined lookup: entity OR attribute matches; useful when query mentions both. */
+    async findByEntityOrAttribute(userId, tokens, limit = 20) {
+        if (tokens.length === 0)
+            return [];
+        const params = [userId];
+        const orClauses = [];
+        tokens.forEach((t) => {
+            params.push(t.toLowerCase());
+            orClauses.push(`lower(entity_name) = $${params.length} OR lower(attribute_key) = $${params.length}`);
+        });
+        params.push(limit);
+        const sql = `SELECT id, user_id, entity_name, attribute_key, attribute_value, value_type,
+              source_memory_id, observed_at, created_at
+       FROM entity_attributes
+       WHERE user_id = $1 AND (${orClauses.join(' OR ')})
+       ORDER BY observed_at DESC
+       LIMIT $${params.length}`;
+        const result = await this.pool.query(sql, params);
+        return result.rows;
+    }
+    async deleteAllForUser(userId) {
+        const result = await this.pool.query('DELETE FROM entity_attributes WHERE user_id = $1', [userId]);
+        return result.rowCount ?? 0;
+    }
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Repository for entity co-occurrence graph operations.
+ * Stores pairwise entity edges per memory and supports neighbor lookups
+ * for spreading activation retrieval.
+ */
+import pg from 'pg';
+export interface EntityEdge {
+    entityA: string;
+    entityB: string;
+    memoryId: string;
+}
+export interface NeighborResult {
+    entity: string;
+    memoryId: string;
+}
+/** Store pairwise entity edges for a single memory. */
+export declare function storeEntityEdges(pool: pg.Pool, userId: string, memoryId: string, entities: string[]): Promise<number>;
+/** Remove all entity edges for a memory (used before UPDATE/SUPERSEDE). */
+export declare function removeEntityEdges(pool: pg.Pool, memoryId: string): Promise<void>;
+/**
+ * Find all neighbors of a set of entities (one hop).
+ * Returns entities connected to any seed entity, along with which memory links them.
+ */
+export declare function findNeighbors(pool: pg.Pool, userId: string, seedEntities: string[]): Promise<NeighborResult[]>;
+/**
+ * Find all memory IDs linked to a set of entities (direct lookup, no traversal).
+ * Used to score memories by accumulated activation after spreading.
+ */
+export declare function findMemoriesForEntities(pool: pg.Pool, userId: string, entities: string[]): Promise<Array<{
+    memoryId: string;
+    entity: string;
+}>>;

package/dist/db/repository-entity-graph.js

@@ -0,0 +1,87 @@
+/**
+ * Repository for entity co-occurrence graph operations.
+ * Stores pairwise entity edges per memory and supports neighbor lookups
+ * for spreading activation retrieval.
+ */
+/** Store pairwise entity edges for a single memory. */
+export async function storeEntityEdges(pool, userId, memoryId, entities) {
+    if (entities.length < 2)
+        return 0;
+    const pairs = buildCanonicalPairs(entities);
+    if (pairs.length === 0)
+        return 0;
+    const values = [];
+    const placeholders = [];
+    let paramIndex = 1;
+    for (const [a, b] of pairs) {
+        placeholders.push(`($${paramIndex}, $${paramIndex + 1}, $${paramIndex + 2}, $${paramIndex + 3})`);
+        values.push(userId, a, b, memoryId);
+        paramIndex += 4;
+    }
+    const sql = `
+    INSERT INTO entity_edges (user_id, entity_a, entity_b, memory_id)
+    VALUES ${placeholders.join(', ')}
+    ON CONFLICT (user_id, entity_a, entity_b, memory_id) DO NOTHING
+  `;
+    await pool.query(sql, values);
+    return pairs.length;
+}
+/** Remove all entity edges for a memory (used before UPDATE/SUPERSEDE). */
+export async function removeEntityEdges(pool, memoryId) {
+    await pool.query('DELETE FROM entity_edges WHERE memory_id = $1', [memoryId]);
+}
+/**
+ * Find all neighbors of a set of entities (one hop).
+ * Returns entities connected to any seed entity, along with which memory links them.
+ */
+export async function findNeighbors(pool, userId, seedEntities) {
+    if (seedEntities.length === 0)
+        return [];
+    const result = await pool.query(`SELECT DISTINCT
+       CASE WHEN entity_a = ANY($2) THEN entity_b ELSE entity_a END AS entity,
+       e.memory_id
+     FROM entity_edges e
+     JOIN memories m ON m.id = e.memory_id AND m.deleted_at IS NULL
+     WHERE e.user_id = $1
+       AND (e.entity_a = ANY($2) OR e.entity_b = ANY($2))`, [userId, seedEntities]);
+    return result.rows;
+}
+/**
+ * Find all memory IDs linked to a set of entities (direct lookup, no traversal).
+ * Used to score memories by accumulated activation after spreading.
+ */
+export async function findMemoriesForEntities(pool, userId, entities) {
+    if (entities.length === 0)
+        return [];
+    const result = await pool.query(`SELECT DISTINCT e.memory_id AS "memoryId",
+       CASE WHEN e.entity_a = ANY($2) THEN e.entity_a ELSE e.entity_b END AS entity
+     FROM entity_edges e
+     JOIN memories m ON m.id = e.memory_id AND m.deleted_at IS NULL
+     WHERE e.user_id = $1
+       AND (e.entity_a = ANY($2) OR e.entity_b = ANY($2))`, [userId, entities]);
+    return result.rows;
+}
+/** Delete all entity edges for a user (used in eval cleanup). */
+async function deleteAllEntityEdges(pool, userId) {
+    if (userId) {
+        await pool.query('DELETE FROM entity_edges WHERE user_id = $1', [userId]);
+    }
+    else {
+        await pool.query('TRUNCATE entity_edges CASCADE');
+    }
+}
+/**
+ * Build canonical pairs from entity list.
+ * Ensures entity_a < entity_b for consistent deduplication.
+ */
+function buildCanonicalPairs(entities) {
+    const pairs = [];
+    for (let i = 0; i < entities.length; i++) {
+        for (let j = i + 1; j < entities.length; j++) {
+            const a = entities[i];
+            const b = entities[j];
+            pairs.push(a < b ? [a, b] : [b, a]);
+        }
+    }
+    return pairs;
+}

package/dist/db/repository-first-mentions.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Repository for first-mention events — per-user chronological list of
+ * "the first time topic X was introduced in conversation."
+ *
+ * Distinct from atomic facts (claims) and memories (chunks). The grain
+ * matches BEAM event-ordering rubrics: which aspects did the user bring
+ * up, and in what order.
+ *
+ * Entries are produced post-ingest by FirstMentionService via a single
+ * LLM scan of the full conversation. Storage is idempotent on
+ * (user_id, memory_id) so re-running the extractor does not duplicate.
+ */
+import pg from 'pg';
+export interface FirstMentionEvent {
+    topic: string;
+    turnId: number;
+    memoryId: string;
+    anchorDate: Date | null;
+    positionInConversation: number;
+}
+export declare class FirstMentionRepository {
+    private pool;
+    constructor(pool: pg.Pool);
+    /**
+     * Idempotent batch INSERT. Conflicts on (user_id, memory_id) are
+     * silently dropped, so re-running the extractor for the same
+     * conversation does not produce duplicate rows.
+     */
+    store(userId: string, sourceSite: string, events: FirstMentionEvent[]): Promise<void>;
+    /**
+     * Look up a single first-mention event by memory_id.
+     * Returns null if no event is associated with the memory.
+     */
+    getByMemoryId(userId: string, memoryId: string): Promise<FirstMentionEvent | null>;
+    /**
+     * List all first-mention events for a user, ordered by
+     * position_in_conversation ASC. Used by EO/MSR retrieval to surface
+     * the chronological topic-introduction list to the answer generator.
+     */
+    list(userId: string, limit?: number): Promise<FirstMentionEvent[]>;
+}

package/dist/db/repository-first-mentions.js

@@ -0,0 +1,79 @@
+/**
+ * Repository for first-mention events — per-user chronological list of
+ * "the first time topic X was introduced in conversation."
+ *
+ * Distinct from atomic facts (claims) and memories (chunks). The grain
+ * matches BEAM event-ordering rubrics: which aspects did the user bring
+ * up, and in what order.
+ *
+ * Entries are produced post-ingest by FirstMentionService via a single
+ * LLM scan of the full conversation. Storage is idempotent on
+ * (user_id, memory_id) so re-running the extractor does not duplicate.
+ */
+export class FirstMentionRepository {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    /**
+     * Idempotent batch INSERT. Conflicts on (user_id, memory_id) are
+     * silently dropped, so re-running the extractor for the same
+     * conversation does not produce duplicate rows.
+     */
+    async store(userId, sourceSite, events) {
+        if (events.length === 0)
+            return;
+        const values = [];
+        const params = [];
+        let p = 1;
+        for (const ev of events) {
+            values.push(`($${p}, $${p + 1}, $${p + 2}, $${p + 3}, $${p + 4}, $${p + 5}, $${p + 6})`);
+            params.push(userId, ev.topic, ev.turnId, ev.memoryId, ev.anchorDate, ev.positionInConversation, sourceSite);
+            p += 7;
+        }
+        await this.pool.query(`INSERT INTO first_mention_events
+        (user_id, topic, turn_id, memory_id, anchor_date,
+         position_in_conversation, source_site)
+        VALUES ${values.join(', ')}
+        ON CONFLICT (user_id, memory_id) DO NOTHING`, params);
+    }
+    /**
+     * Look up a single first-mention event by memory_id.
+     * Returns null if no event is associated with the memory.
+     */
+    async getByMemoryId(userId, memoryId) {
+        const result = await this.pool.query(`SELECT topic, turn_id, memory_id, anchor_date, position_in_conversation
+       FROM first_mention_events
+       WHERE user_id = $1 AND memory_id = $2
+       LIMIT 1`, [userId, memoryId]);
+        if (result.rows.length === 0)
+            return null;
+        const row = result.rows[0];
+        return {
+            topic: row.topic,
+            turnId: row.turn_id,
+            memoryId: row.memory_id,
+            anchorDate: row.anchor_date,
+            positionInConversation: row.position_in_conversation,
+        };
+    }
+    /**
+     * List all first-mention events for a user, ordered by
+     * position_in_conversation ASC. Used by EO/MSR retrieval to surface
+     * the chronological topic-introduction list to the answer generator.
+     */
+    async list(userId, limit = 100) {
+        const result = await this.pool.query(`SELECT topic, turn_id, memory_id, anchor_date, position_in_conversation
+       FROM first_mention_events
+       WHERE user_id = $1
+       ORDER BY position_in_conversation ASC
+       LIMIT $2`, [userId, limit]);
+        return result.rows.map((row) => ({
+            topic: row.topic,
+            turnId: row.turn_id,
+            memoryId: row.memory_id,
+            anchorDate: row.anchor_date,
+            positionInConversation: row.position_in_conversation,
+        }));
+    }
+}

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

@@ -0,0 +1,51 @@
+/**
+ * Lesson repository — CRUD and similarity search for detected failure patterns.
+ *
+ * Lessons capture attack/failure patterns from sanitization blocks, trust
+ * violations, contradictions, and user reports. Pre-retrieval checks query
+ * lessons by embedding similarity to block known-bad patterns before they
+ * reach the user.
+ *
+ * Phase 6 (A-MemGuard): self-reinforcing defense via pattern accumulation.
+ */
+import pg from 'pg';
+export type LessonType = 'injection_blocked' | 'false_memory' | 'contradiction_pattern' | 'user_reported' | 'consensus_violation' | 'trust_violation';
+export type LessonSeverity = 'low' | 'medium' | 'high' | 'critical';
+export interface LessonRow {
+    id: string;
+    user_id: string;
+    lesson_type: LessonType;
+    pattern: string;
+    embedding: number[];
+    source_memory_ids: string[];
+    source_query: string | null;
+    severity: LessonSeverity;
+    active: boolean;
+    metadata: Record<string, unknown>;
+    created_at: Date;
+}
+export interface CreateLessonInput {
+    userId: string;
+    lessonType: LessonType;
+    pattern: string;
+    embedding: number[];
+    sourceMemoryIds?: string[];
+    sourceQuery?: string;
+    severity?: LessonSeverity;
+    metadata?: Record<string, unknown>;
+}
+export interface LessonMatch {
+    lesson: LessonRow;
+    similarity: number;
+}
+export declare class LessonRepository {
+    private pool;
+    constructor(pool: pg.Pool);
+    createLesson(input: CreateLessonInput): Promise<string>;
+    findSimilarLessons(userId: string, embedding: number[], threshold: number, limit?: number): Promise<LessonMatch[]>;
+    getLessonsByUser(userId: string, activeOnly?: boolean): Promise<LessonRow[]>;
+    getLessonsByType(userId: string, lessonType: LessonType): Promise<LessonRow[]>;
+    deactivateLesson(userId: string, lessonId: string): Promise<void>;
+    countActiveLessons(userId: string): Promise<number>;
+    deleteAll(): Promise<void>;
+}

package/dist/db/repository-lessons.js

@@ -0,0 +1,90 @@
+/**
+ * Lesson repository — CRUD and similarity search for detected failure patterns.
+ *
+ * Lessons capture attack/failure patterns from sanitization blocks, trust
+ * violations, contradictions, and user reports. Pre-retrieval checks query
+ * lessons by embedding similarity to block known-bad patterns before they
+ * reach the user.
+ *
+ * Phase 6 (A-MemGuard): self-reinforcing defense via pattern accumulation.
+ */
+import pgvector from 'pgvector/pg';
+import { config } from '../config.js';
+export class LessonRepository {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async createLesson(input) {
+        const result = await this.pool.query(`INSERT INTO lessons (user_id, lesson_type, pattern, embedding, source_memory_ids, source_query, severity, metadata)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+       RETURNING id`, [
+            input.userId,
+            input.lessonType,
+            input.pattern,
+            pgvector.toSql(input.embedding),
+            input.sourceMemoryIds ?? [],
+            input.sourceQuery ?? null,
+            input.severity ?? 'medium',
+            JSON.stringify(input.metadata ?? {}),
+        ]);
+        return result.rows[0].id;
+    }
+    async findSimilarLessons(userId, embedding, threshold, limit = 5) {
+        const result = await this.pool.query(`SELECT *, 1 - (embedding <=> $1) AS similarity
+       FROM lessons
+       WHERE user_id = $2 AND active = true
+         AND 1 - (embedding <=> $1) >= $3
+       ORDER BY similarity DESC
+       LIMIT $4`, [pgvector.toSql(embedding), userId, threshold, limit]);
+        return result.rows.map((row) => ({
+            lesson: parseRow(row),
+            similarity: parseFloat(row.similarity),
+        }));
+    }
+    async getLessonsByUser(userId, activeOnly = true) {
+        const activeClause = activeOnly ? 'AND active = true' : '';
+        const result = await this.pool.query(`SELECT * FROM lessons WHERE user_id = $1 ${activeClause} ORDER BY created_at DESC`, [userId]);
+        return result.rows.map(parseRow);
+    }
+    async getLessonsByType(userId, lessonType) {
+        const result = await this.pool.query(`SELECT * FROM lessons WHERE user_id = $1 AND lesson_type = $2 AND active = true ORDER BY created_at DESC`, [userId, lessonType]);
+        return result.rows.map(parseRow);
+    }
+    async deactivateLesson(userId, lessonId) {
+        await this.pool.query(`UPDATE lessons SET active = false WHERE id = $1 AND user_id = $2`, [lessonId, userId]);
+    }
+    async countActiveLessons(userId) {
+        const result = await this.pool.query(`SELECT COUNT(*)::int AS count FROM lessons WHERE user_id = $1 AND active = true`, [userId]);
+        return result.rows[0].count;
+    }
+    async deleteAll() {
+        await this.pool.query('DELETE FROM lessons');
+    }
+}
+function parseRow(row) {
+    const rawEmb = row.embedding;
+    let embedding;
+    if (typeof rawEmb === 'string') {
+        embedding = rawEmb.replace(/[\[\]]/g, '').split(',').map(Number);
+    }
+    else if (Array.isArray(rawEmb)) {
+        embedding = rawEmb;
+    }
+    else {
+        embedding = Array(config.embeddingDimensions).fill(0);
+    }
+    return {
+        id: row.id,
+        user_id: row.user_id,
+        lesson_type: row.lesson_type,
+        pattern: row.pattern,
+        embedding,
+        source_memory_ids: row.source_memory_ids ?? [],
+        source_query: row.source_query ?? null,
+        severity: row.severity,
+        active: row.active,
+        metadata: (typeof row.metadata === 'string' ? JSON.parse(row.metadata) : row.metadata ?? {}),
+        created_at: row.created_at,
+    };
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Memory link storage and 1-hop traversal queries.
+ *
+ * Links are bidirectional pairs stored with source_id < target_id to avoid
+ * duplicates. Generated at write time when embedding similarity exceeds the
+ * configured threshold (Phase 2 roadmap, A-MEM pattern).
+ */
+import pg from 'pg';
+import { type SearchResult } from './repository-types.js';
+export interface MemoryLink {
+    sourceId: string;
+    targetId: string;
+    similarity: number;
+}
+export declare function createLinks(pool: pg.Pool, links: MemoryLink[]): Promise<number>;
+export declare function findLinkedMemoryIds(pool: pg.Pool, memoryIds: string[], excludeIds: Set<string>, limit: number): Promise<string[]>;
+export declare function fetchMemoriesByIds(pool: pg.Pool, userId: string, ids: string[], queryEmbedding: number[], referenceTime?: Date, includeExpired?: boolean): Promise<SearchResult[]>;
+export declare function findLinkCandidates(pool: pg.Pool, userId: string, embedding: number[], threshold: number, excludeId: string, limit: number): Promise<Array<{
+    id: string;
+    similarity: number;
+}>>;
+export declare function findLinkCandidatesWithClient(client: pg.PoolClient, userId: string, embedding: number[], threshold: number, excludeId: string, limit: number): Promise<Array<{
+    id: string;
+    similarity: number;
+}>>;
+export declare function countLinks(pool: pg.Pool): Promise<number>;

package/dist/db/repository-links.js

@@ -0,0 +1,105 @@
+/**
+ * Memory link storage and 1-hop traversal queries.
+ *
+ * Links are bidirectional pairs stored with source_id < target_id to avoid
+ * duplicates. Generated at write time when embedding similarity exceeds the
+ * configured threshold (Phase 2 roadmap, A-MEM pattern).
+ */
+import pgvector from 'pgvector/pg';
+import { config } from '../config.js';
+import { normalizeSearchRow } from './repository-types.js';
+export async function createLinks(pool, links) {
+    return createLinksWithClient(pool, links);
+}
+async function createLinksWithClient(client, links) {
+    if (links.length === 0)
+        return 0;
+    const deduped = new Map();
+    for (const link of links) {
+        const [lo, hi] = canonicalPair(link.sourceId, link.targetId);
+        const key = `${lo}:${hi}`;
+        const existing = deduped.get(key);
+        if (!existing || link.similarity > existing.similarity) {
+            deduped.set(key, { lo, hi, similarity: link.similarity });
+        }
+    }
+    const values = [];
+    const params = [];
+    for (const { lo, hi, similarity } of deduped.values()) {
+        const offset = params.length;
+        values.push(`($${offset + 1}, $${offset + 2}, $${offset + 3})`);
+        params.push(lo, hi, similarity);
+    }
+    const result = await client.query(`INSERT INTO memory_links (source_id, target_id, similarity)
+     VALUES ${values.join(', ')}
+     ON CONFLICT (source_id, target_id)
+     DO UPDATE SET similarity = EXCLUDED.similarity
+     RETURNING source_id`, params);
+    return result.rowCount ?? 0;
+}
+export async function findLinkedMemoryIds(pool, memoryIds, excludeIds, limit) {
+    if (memoryIds.length === 0)
+        return [];
+    const result = await pool.query(`SELECT DISTINCT links.linked_id, links.similarity FROM (
+       SELECT target_id AS linked_id, similarity
+       FROM memory_links WHERE source_id = ANY($1)
+       UNION ALL
+       SELECT source_id AS linked_id, similarity
+       FROM memory_links WHERE target_id = ANY($1)
+     ) AS links
+     JOIN memories m ON m.id = links.linked_id AND m.workspace_id IS NULL
+     ORDER BY links.similarity DESC
+     LIMIT $2`, [memoryIds, limit * 2]);
+    return result.rows
+        .map((row) => row.linked_id)
+        .filter((id) => !excludeIds.has(id))
+        .slice(0, limit);
+}
+export async function fetchMemoriesByIds(pool, userId, ids, queryEmbedding, referenceTime, includeExpired = false) {
+    if (ids.length === 0)
+        return [];
+    const wSim = config.scoringWeightSimilarity;
+    const wImp = config.scoringWeightImportance;
+    const wRec = config.scoringWeightRecency;
+    const refTime = (referenceTime ?? new Date()).toISOString();
+    const expiredClause = includeExpired ? '' : 'AND expired_at IS NULL';
+    const result = await pool.query(`SELECT *,
+       1 - (embedding <=> $1) AS similarity,
+       (
+         $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
+     FROM memories
+     WHERE id = ANY($2)
+       AND user_id = $3
+       AND deleted_at IS NULL
+       ${expiredClause}
+       AND status = 'active'
+       AND workspace_id IS NULL
+     ORDER BY score DESC`, [pgvector.toSql(queryEmbedding), ids, userId, wSim, wImp, wRec, refTime]);
+    return result.rows.map(normalizeSearchRow);
+}
+export async function findLinkCandidates(pool, userId, embedding, threshold, excludeId, limit) {
+    return findLinkCandidatesWithClient(pool, userId, embedding, threshold, excludeId, limit);
+}
+export async function findLinkCandidatesWithClient(client, userId, embedding, threshold, excludeId, limit) {
+    const result = await client.query(`SELECT id, 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 id != $3
+       AND 1 - (embedding <=> $1) > $4
+     ORDER BY similarity DESC
+     LIMIT $5`, [pgvector.toSql(embedding), userId, excludeId, threshold, limit]);
+    return result.rows;
+}
+export async function countLinks(pool) {
+    const result = await pool.query('SELECT COUNT(*)::int AS count FROM memory_links');
+    return result.rows[0].count;
+}
+function canonicalPair(a, b) {
+    return a < b ? [a, b] : [b, a];
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Repository for observation network dirty-marking and regeneration queries.
+ * Observations are synthesized entity profiles — regenerated asynchronously
+ * when new facts about an entity are ingested.
+ */
+import pg from 'pg';
+export declare class ObservationRepository {
+    private pool;
+    constructor(pool: pg.Pool);
+    /** Mark entity subjects as needing observation regeneration. Idempotent. */
+    markDirty(userId: string, subjects: string[]): Promise<void>;
+    /** Get all pending observation regeneration tasks. */
+    getPending(limit?: number): Promise<Array<{
+        userId: string;
+        subject: string;
+    }>>;
+    /** Clear a dirty mark after successful regeneration. */
+    clearDirty(userId: string, subject: string): Promise<void>;
+    /** Find all memory content linked to a subject entity for synthesis. */
+    findMemoriesForSubject(userId: string, subject: string): Promise<Array<{
+        id: string;
+        content: string;
+    }>>;
+    /** Find the existing observation for a subject (to expire it on regeneration). */
+    findExistingObservation(userId: string, subject: string): Promise<string | null>;
+}

package/dist/db/repository-observation.js

@@ -0,0 +1,51 @@
+/**
+ * Repository for observation network dirty-marking and regeneration queries.
+ * Observations are synthesized entity profiles — regenerated asynchronously
+ * when new facts about an entity are ingested.
+ */
+export class ObservationRepository {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    /** Mark entity subjects as needing observation regeneration. Idempotent. */
+    async markDirty(userId, subjects) {
+        if (subjects.length === 0)
+            return;
+        const values = subjects.map((_, i) => `($1, $${i + 2}, NOW())`).join(', ');
+        await this.pool.query(`INSERT INTO observation_dirty (user_id, subject, marked_at) VALUES ${values}
+       ON CONFLICT (user_id, subject) DO UPDATE SET marked_at = NOW()`, [userId, ...subjects]);
+    }
+    /** Get all pending observation regeneration tasks. */
+    async getPending(limit = 50) {
+        const result = await this.pool.query(`SELECT user_id, subject FROM observation_dirty ORDER BY marked_at ASC LIMIT $1`, [limit]);
+        return result.rows.map((r) => ({ userId: r.user_id, subject: r.subject }));
+    }
+    /** Clear a dirty mark after successful regeneration. */
+    async clearDirty(userId, subject) {
+        await this.pool.query(`DELETE FROM observation_dirty WHERE user_id = $1 AND subject = $2`, [userId, subject]);
+    }
+    /** Find all memory content linked to a subject entity for synthesis. */
+    async findMemoriesForSubject(userId, subject) {
+        const result = await this.pool.query(`SELECT DISTINCT m.id, m.content, m.created_at
+       FROM memories m
+       JOIN memory_entities me ON me.memory_id = m.id
+       JOIN entities e ON e.id = me.entity_id
+       WHERE m.user_id = $1
+         AND (e.name ILIKE $2 OR $2 = ANY(e.alias_names))
+         AND m.deleted_at IS NULL AND m.expired_at IS NULL
+         AND m.network != 'observation'
+       ORDER BY m.created_at DESC
+       LIMIT 50`, [userId, subject]);
+        return result.rows;
+    }
+    /** Find the existing observation for a subject (to expire it on regeneration). */
+    async findExistingObservation(userId, subject) {
+        const result = await this.pool.query(`SELECT id FROM memories
+       WHERE user_id = $1 AND network = 'observation'
+         AND observation_subject = $2
+         AND deleted_at IS NULL AND expired_at IS NULL
+       LIMIT 1`, [userId, subject]);
+        return result.rows[0]?.id ?? null;
+    }
+}