@atomicmemory/core 1.0.0

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

@@ -0,0 +1,56 @@
+/**
+ * Read-side queries for active memory projections.
+ */
+import pg from 'pg';
+import { type EpisodeRow, type MemoryRow, type SearchResult } from './repository-types.js';
+import type { AgentScope } from './repository-types.js';
+export declare function getEpisode(pool: pg.Pool, id: string): Promise<EpisodeRow | null>;
+export declare function getMemory(pool: pg.Pool, id: string, userId?: string, includeDeleted?: boolean): Promise<MemoryRow | null>;
+export declare function getMemoryWithClient(client: pg.PoolClient, id: string, userId?: string, includeDeleted?: boolean): Promise<MemoryRow | null>;
+export declare function listMemories(pool: pg.Pool, userId: string, limit: number, offset: number, sourceSite?: string, episodeId?: string): Promise<MemoryRow[]>;
+export declare function listMemoriesInWorkspace(pool: pg.Pool, workspaceId: string, limit: number, offset: number, callerAgentId?: string): Promise<MemoryRow[]>;
+export declare function getMemoryInWorkspace(pool: pg.Pool, id: string, workspaceId: string, callerAgentId?: string): Promise<MemoryRow | null>;
+export declare function listMemoriesByNamespace(pool: pg.Pool, userId: string, namespace: string, limit?: number): Promise<MemoryRow[]>;
+export declare function getMemoryStats(pool: pg.Pool, userId: string): Promise<{
+    count: number;
+    avgImportance: number;
+    sourceDistribution: Record<string, number>;
+}>;
+export declare function searchSimilar(pool: pg.Pool, userId: string, queryEmbedding: number[], limit: number, sourceSite?: string, referenceTime?: Date): Promise<SearchResult[]>;
+export declare function searchHybridSimilar(pool: pg.Pool, userId: string, queryText: string, queryEmbedding: number[], limit: number, sourceSite?: string, referenceTime?: Date): Promise<SearchResult[]>;
+export declare function searchKeywordSimilar(pool: pg.Pool, userId: string, queryText: string, limit: number, sourceSite?: string): Promise<SearchResult[]>;
+export declare function findNearDuplicates(pool: pg.Pool, userId: string, embedding: number[], threshold: number, limit: number): Promise<import("./repository-vector-search.js").CandidateRow[]>;
+/**
+ * Workspace-scoped vector search with agent filtering and visibility enforcement.
+ */
+export declare function searchSimilarInWorkspace(pool: pg.Pool, workspaceId: string, queryEmbedding: number[], limit: number, agentScope?: AgentScope, callerAgentId?: string, referenceTime?: Date): Promise<SearchResult[]>;
+/**
+ * Find near-duplicate memories within a workspace scope for AUDN conflict detection.
+ */
+export declare function findNearDuplicatesInWorkspace(pool: pg.Pool, workspaceId: string, embedding: number[], threshold: number, limit: number, agentScope?: AgentScope, callerAgentId?: string): Promise<import("./repository-vector-search.js").CandidateRow[]>;
+export declare function findKeywordCandidates(pool: pg.Pool, userId: string, keywords: string[], limit: number, includeExpired?: boolean): Promise<any[]>;
+/**
+ * Find candidate memories by topic-embedding similarity (Sprint 3 EO experiment).
+ *
+ * Returns rows whose `topic_embedding` (LLM-generated 3-7 word topic, embedded
+ * separately from the raw fact) is closest to the query embedding. Used as a
+ * dedicated RRF channel by the search pipeline when topicSearchEnabled=true.
+ *
+ * Skips rows with NULL topic_embedding so legacy memories don't pollute the
+ * candidate set. The HNSW index on the partial column makes this fast.
+ */
+export declare function findTopicCandidates(pool: pg.Pool, userId: string, queryEmbedding: number[], limit: number): Promise<{
+    id: string;
+    content: string;
+    topic_abstraction: string;
+    importance: number;
+    similarity: number;
+}[]>;
+export declare function countMemories(pool: pg.Pool, userId?: string): Promise<number>;
+export declare function countNeedsClarification(pool: pg.Pool, userId: string): Promise<number>;
+/**
+ * Finds memories created within a time window of the given anchor timestamps.
+ * Used for 1-hop temporal-neighbor expansion: surfaces facts from the same
+ * conversation session that the initial top-K results originated from.
+ */
+export declare function findTemporalNeighbors(pool: pg.Pool, userId: string, anchorTimestamps: Date[], queryEmbedding: number[], windowMinutes: number, excludeIds: Set<string>, limit: number, referenceTime?: Date): Promise<SearchResult[]>;

package/dist/db/repository-read.js

@@ -0,0 +1,271 @@
+/**
+ * Read-side queries for active memory projections.
+ */
+import { config } from '../config.js';
+import { normalizeMemoryRow, normalizeSearchRow, } from './repository-types.js';
+import { findDuplicateVectors, findDuplicateVectorsInWorkspace, searchHybrid, searchKeyword, searchVectors, searchVectorsInWorkspace, } from './repository-vector-search.js';
+export async function getEpisode(pool, id) {
+    const result = await pool.query('SELECT * FROM episodes WHERE id = $1', [id]);
+    return result.rows[0] ?? null;
+}
+export async function getMemory(pool, id, userId, includeDeleted = false) {
+    return getMemoryWithClient(pool, id, userId, includeDeleted);
+}
+export async function getMemoryWithClient(client, id, userId, includeDeleted = false) {
+    const clauses = ['id = $1'];
+    const params = [id];
+    if (userId) {
+        clauses.push(`user_id = $${params.length + 1}`);
+        params.push(userId);
+    }
+    if (!includeDeleted) {
+        clauses.push('deleted_at IS NULL');
+        clauses.push('expired_at IS NULL');
+    }
+    const result = await client.query(`SELECT * FROM memories WHERE ${clauses.join(' AND ')}`, params);
+    return result.rows[0] ? normalizeMemoryRow(result.rows[0]) : null;
+}
+export async function listMemories(pool, userId, limit, offset, sourceSite, episodeId) {
+    const params = [userId, limit, offset];
+    let extraClauses = '';
+    if (sourceSite) {
+        params.push(sourceSite);
+        extraClauses += ` AND source_site = $${params.length}`;
+    }
+    if (episodeId) {
+        params.push(episodeId);
+        extraClauses += ` AND episode_id = $${params.length}`;
+    }
+    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${extraClauses}
+     ORDER BY created_at DESC LIMIT $2 OFFSET $3`, params);
+    return result.rows.map(normalizeMemoryRow);
+}
+export async function listMemoriesInWorkspace(pool, workspaceId, limit, offset, callerAgentId) {
+    const params = [workspaceId];
+    let visibilityClause = '';
+    if (callerAgentId) {
+        params.push(callerAgentId);
+        visibilityClause = buildVisibilityClause(params.length);
+    }
+    params.push(limit, offset);
+    const result = await pool.query(`SELECT * FROM memories
+     WHERE workspace_id = $1 AND deleted_at IS NULL AND expired_at IS NULL AND status = 'active'
+     ${visibilityClause}
+     ORDER BY created_at DESC LIMIT $${params.length - 1} OFFSET $${params.length}`, params);
+    return result.rows.map(normalizeMemoryRow);
+}
+export async function getMemoryInWorkspace(pool, id, workspaceId, callerAgentId) {
+    const params = [id, workspaceId];
+    let visibilityClause = '';
+    if (callerAgentId) {
+        params.push(callerAgentId);
+        visibilityClause = buildVisibilityClause(params.length);
+    }
+    const result = await pool.query(`SELECT * FROM memories WHERE id = $1 AND workspace_id = $2 AND deleted_at IS NULL ${visibilityClause}`, params);
+    return result.rows[0] ? normalizeMemoryRow(result.rows[0]) : null;
+}
+/**
+ * Build agent visibility enforcement clause.
+ * Replicates the logic from buildVisibilityClauseForSearch in repository-vector-search.ts.
+ */
+function buildVisibilityClause(agentParamIndex) {
+    return `AND (
+    visibility = 'workspace'
+    OR visibility IS NULL
+    OR (visibility = 'agent_only' AND agent_id = $${agentParamIndex})
+    OR (visibility = 'restricted' AND (
+      agent_id = $${agentParamIndex}
+      OR EXISTS (
+        SELECT 1 FROM memory_visibility_grants g
+        WHERE g.memory_id = memories.id AND g.grantee_agent_id = $${agentParamIndex}
+      )
+    ))
+  )`;
+}
+export async function listMemoriesByNamespace(pool, userId, namespace, limit = 20) {
+    const result = await pool.query(`SELECT * FROM memories
+     WHERE user_id = $1
+       AND namespace = $2
+       AND deleted_at IS NULL
+       AND expired_at IS NULL
+       AND status = 'active'
+     ORDER BY created_at DESC
+     LIMIT $3`, [userId, namespace, limit]);
+    return result.rows.map(normalizeMemoryRow);
+}
+export async function getMemoryStats(pool, userId) {
+    const counts = await pool.query(`SELECT COUNT(*)::int AS count, AVG(importance) AS avg_importance
+     FROM memories WHERE user_id = $1 AND deleted_at IS NULL AND expired_at IS NULL AND status = 'active'`, [userId]);
+    const sources = await pool.query(`SELECT source_site, COUNT(*)::int AS count
+     FROM memories WHERE user_id = $1 AND deleted_at IS NULL AND expired_at IS NULL AND status = 'active'
+     GROUP BY source_site`, [userId]);
+    return {
+        count: counts.rows[0].count ?? 0,
+        avgImportance: Number(counts.rows[0].avg_importance ?? 0),
+        sourceDistribution: Object.fromEntries(sources.rows.map((row) => [row.source_site, row.count])),
+    };
+}
+export async function searchSimilar(pool, userId, queryEmbedding, limit, sourceSite, referenceTime) {
+    return searchVectors(pool, userId, queryEmbedding, limit, sourceSite, referenceTime);
+}
+export async function searchHybridSimilar(pool, userId, queryText, queryEmbedding, limit, sourceSite, referenceTime) {
+    return searchHybrid(pool, userId, queryText, queryEmbedding, limit, sourceSite, referenceTime);
+}
+export async function searchKeywordSimilar(pool, userId, queryText, limit, sourceSite) {
+    return searchKeyword(pool, userId, queryText, limit, sourceSite);
+}
+export async function findNearDuplicates(pool, userId, embedding, threshold, limit) {
+    return findDuplicateVectors(pool, userId, embedding, threshold, limit);
+}
+/**
+ * Workspace-scoped vector search with agent filtering and visibility enforcement.
+ */
+export async function searchSimilarInWorkspace(pool, workspaceId, queryEmbedding, limit, agentScope = 'all', callerAgentId, referenceTime) {
+    return searchVectorsInWorkspace(pool, workspaceId, queryEmbedding, limit, agentScope, callerAgentId, referenceTime);
+}
+/**
+ * Find near-duplicate memories within a workspace scope for AUDN conflict detection.
+ */
+export async function findNearDuplicatesInWorkspace(pool, workspaceId, embedding, threshold, limit, agentScope = 'all', callerAgentId) {
+    return findDuplicateVectorsInWorkspace(pool, workspaceId, embedding, threshold, limit, agentScope, callerAgentId);
+}
+export async function findKeywordCandidates(pool, userId, keywords, limit, includeExpired = false) {
+    if (keywords.length === 0)
+        return [];
+    const candidateLimit = Math.max(limit * 4, limit);
+    const expiredClause = includeExpired ? '' : 'AND expired_at IS NULL';
+    const result = await pool.query(`SELECT id, content, importance
+     FROM memories
+     WHERE user_id = $1
+       AND deleted_at IS NULL
+       ${expiredClause}
+       AND status = 'active'
+       AND workspace_id IS NULL
+       AND content ILIKE ANY($2::text[])
+     ORDER BY importance DESC, created_at DESC
+     LIMIT $3`, [userId, keywords.map((keyword) => `%${keyword}%`), candidateLimit]);
+    return result.rows
+        .map((row) => ({
+        ...row,
+        similarity: estimateKeywordSimilarity(row.content, keywords),
+    }))
+        .sort((left, right) => {
+        if (right.similarity !== left.similarity) {
+            return right.similarity - left.similarity;
+        }
+        return Number(right.importance) - Number(left.importance);
+    })
+        .slice(0, limit);
+}
+/**
+ * Find candidate memories by topic-embedding similarity (Sprint 3 EO experiment).
+ *
+ * Returns rows whose `topic_embedding` (LLM-generated 3-7 word topic, embedded
+ * separately from the raw fact) is closest to the query embedding. Used as a
+ * dedicated RRF channel by the search pipeline when topicSearchEnabled=true.
+ *
+ * Skips rows with NULL topic_embedding so legacy memories don't pollute the
+ * candidate set. The HNSW index on the partial column makes this fast.
+ */
+export async function findTopicCandidates(pool, userId, queryEmbedding, limit) {
+    const result = await pool.query(`SELECT id, content, topic_abstraction, importance,
+            1 - (topic_embedding <=> $2::vector) AS similarity
+     FROM memories
+     WHERE user_id = $1
+       AND deleted_at IS NULL
+       AND expired_at IS NULL
+       AND status = 'active'
+       AND workspace_id IS NULL
+       AND topic_embedding IS NOT NULL
+     ORDER BY topic_embedding <=> $2::vector
+     LIMIT $3`, [userId, JSON.stringify(queryEmbedding), limit]);
+    return result.rows.map((row) => ({
+        id: row.id,
+        content: row.content,
+        topic_abstraction: row.topic_abstraction,
+        importance: Number(row.importance),
+        similarity: Number(row.similarity),
+    }));
+}
+export async function countMemories(pool, userId) {
+    const query = userId
+        ? `SELECT COUNT(*)::int AS count FROM memories WHERE user_id = $1 AND deleted_at IS NULL AND expired_at IS NULL AND status = 'active'`
+        : `SELECT COUNT(*)::int AS count FROM memories WHERE deleted_at IS NULL AND expired_at IS NULL AND status = 'active'`;
+    const result = await pool.query(query, userId ? [userId] : []);
+    return result.rows[0].count;
+}
+export async function countNeedsClarification(pool, userId) {
+    const result = await pool.query(`SELECT COUNT(*)::int AS count
+     FROM memories WHERE user_id = $1 AND deleted_at IS NULL AND expired_at IS NULL AND status = 'needs_clarification'`, [userId]);
+    return result.rows[0].count;
+}
+/**
+ * Finds memories created within a time window of the given anchor timestamps.
+ * Used for 1-hop temporal-neighbor expansion: surfaces facts from the same
+ * conversation session that the initial top-K results originated from.
+ */
+export async function findTemporalNeighbors(pool, userId, anchorTimestamps, queryEmbedding, windowMinutes, excludeIds, limit, referenceTime) {
+    if (anchorTimestamps.length === 0 || limit <= 0)
+        return [];
+    const pgvector = await import('pgvector/pg');
+    const excludeArray = [...excludeIds];
+    const windowInterval = `${windowMinutes} minutes`;
+    const wSim = config.scoringWeightSimilarity;
+    const wImp = config.scoringWeightImportance;
+    const wRec = config.scoringWeightRecency;
+    const refTime = (referenceTime ?? new Date()).toISOString();
+    const result = await pool.query(`SELECT *,
+       1 - (embedding <=> $1) AS similarity,
+       (
+         $7 * (1 - (embedding <=> $1))
+         + $8 * importance
+         + $9 * EXP(-EXTRACT(EPOCH FROM ($10::timestamptz - last_accessed_at)) / 2592000.0)
+       ) * COALESCE(trust_score, 1.0) AS 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
+       AND id != ALL($3::uuid[])
+       AND EXISTS (
+         SELECT 1 FROM unnest($4::timestamptz[]) AS anchor
+         WHERE memories.created_at BETWEEN anchor - $5::interval AND anchor + $5::interval
+       )
+     ORDER BY score DESC
+     LIMIT $6`, [
+        pgvector.default.toSql(queryEmbedding),
+        userId,
+        excludeArray,
+        anchorTimestamps,
+        windowInterval,
+        limit,
+        wSim, wImp, wRec, refTime,
+    ]);
+    return result.rows.map(normalizeSearchRow);
+}
+function estimateKeywordSimilarity(content, keywords) {
+    const lower = content.toLowerCase();
+    const weights = keywords.map((keyword) => keywordWeight(keyword));
+    const totalWeight = weights.reduce((sum, weight) => sum + weight, 0);
+    if (totalWeight === 0)
+        return 0.45;
+    let matchedWeight = 0;
+    for (let i = 0; i < keywords.length; i++) {
+        if (lower.includes(keywords[i].toLowerCase())) {
+            matchedWeight += weights[i];
+        }
+    }
+    return Math.min(0.89, 0.45 + (0.44 * matchedWeight / totalWeight));
+}
+function keywordWeight(keyword) {
+    if (keyword.includes(' '))
+        return 2.5;
+    if (/^[A-Z]{3,}$/.test(keyword) || /[A-Z]/.test(keyword.slice(1)))
+        return 2;
+    if (keyword.length >= 8)
+        return 1.5;
+    return 1;
+}

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

@@ -0,0 +1,59 @@
+/**
+ * Repository for the Recap layer (Sprint 3 v1).
+ *
+ * Handles read + write for the `episodes` table and the cross-table
+ * "find unconsolidated clusters" query that drives the Recap builder's
+ * background pass.
+ */
+import pg from 'pg';
+export interface RecapRow {
+    id: string;
+    user_id: string;
+    recap_text: string;
+    /** Pre-computed recap embedding — surfaced so downstream MMR can compute cosine similarity without re-embedding. */
+    recap_embedding: number[];
+    topic: string;
+    member_count: number;
+    similarity: number;
+}
+export interface UnconsolidatedCluster {
+    topic: string;
+    member_ids: string[];
+    member_contents: string[];
+    time_range_start: Date | null;
+    time_range_end: Date | null;
+}
+export interface StoreRecapInput {
+    userId: string;
+    recapText: string;
+    recapEmbedding: number[];
+    topic: string;
+    memberMemoryIds: string[];
+    timeRangeStart: Date | null;
+    timeRangeEnd: Date | null;
+}
+export type RecapClusterPivot = 'topic' | 'session';
+/**
+ * Find clusters of un-consolidated memories for a given user.
+ *
+ * Two pivots supported:
+ *   'topic'   — cluster by topic_abstraction (requires topic-abstraction
+ *               layer ON at ingest). Original Sprint 3 v1 design.
+ *               Empirically regressed fact-anchored abilities; v2 backlog #2
+ *               re-pivots to 'session'.
+ *   'session' — cluster by user_id + observed_at hour bucket. Captures
+ *               cross-turn aggregation within a conversation/session window
+ *               without depending on the broken topic-abstraction layer.
+ */
+export declare function findUnconsolidatedClusters(pool: pg.Pool, userId: string, minSize: number, pivot?: RecapClusterPivot): Promise<UnconsolidatedCluster[]>;
+/**
+ * Insert a new episode and mark its member memories as consolidated.
+ * Wrapped in a transaction so member-flag updates can't drift from the
+ * episode insert.
+ */
+export declare function storeRecap(pool: pg.Pool, input: StoreRecapInput): Promise<string>;
+/**
+ * Find episode candidates by embedding similarity. Used as a dedicated
+ * RRF channel at retrieval.
+ */
+export declare function findRecapCandidates(pool: pg.Pool, userId: string, queryEmbedding: number[], limit: number): Promise<RecapRow[]>;

package/dist/db/repository-recaps.js

@@ -0,0 +1,158 @@
+/**
+ * Repository for the Recap layer (Sprint 3 v1).
+ *
+ * Handles read + write for the `episodes` table and the cross-table
+ * "find unconsolidated clusters" query that drives the Recap builder's
+ * background pass.
+ */
+/** Parse pgvector's text representation `[1.2, 3.4, ...]` into number[]. */
+function parsePgVector(s) {
+    if (!s)
+        return [];
+    const trimmed = s.trim().replace(/^\[|\]$/g, '');
+    if (!trimmed)
+        return [];
+    return trimmed.split(',').map((x) => Number(x.trim()));
+}
+/**
+ * Find clusters of un-consolidated memories for a given user.
+ *
+ * Two pivots supported:
+ *   'topic'   — cluster by topic_abstraction (requires topic-abstraction
+ *               layer ON at ingest). Original Sprint 3 v1 design.
+ *               Empirically regressed fact-anchored abilities; v2 backlog #2
+ *               re-pivots to 'session'.
+ *   'session' — cluster by user_id + observed_at hour bucket. Captures
+ *               cross-turn aggregation within a conversation/session window
+ *               without depending on the broken topic-abstraction layer.
+ */
+export async function findUnconsolidatedClusters(pool, userId, minSize, pivot = 'topic') {
+    return pivot === 'session'
+        ? findUnconsolidatedSessionClusters(pool, userId, minSize)
+        : findUnconsolidatedTopicClusters(pool, userId, minSize);
+}
+async function findUnconsolidatedTopicClusters(pool, userId, minSize) {
+    const result = await pool.query(`SELECT topic_abstraction AS topic,
+            array_agg(id ORDER BY observed_at) AS member_ids,
+            array_agg(content ORDER BY observed_at) AS member_contents,
+            MIN(observed_at) AS time_start,
+            MAX(observed_at) AS time_end,
+            COUNT(*) AS n
+     FROM memories
+     WHERE user_id = $1
+       AND deleted_at IS NULL
+       AND expired_at IS NULL
+       AND status = 'active'
+       AND workspace_id IS NULL
+       AND topic_abstraction IS NOT NULL
+       AND topic_abstraction <> ''
+       AND recap_id IS NULL
+     GROUP BY topic_abstraction
+     HAVING COUNT(*) >= $2
+     ORDER BY COUNT(*) DESC
+     LIMIT 32`, [userId, minSize]);
+    return result.rows.map((row) => ({
+        topic: row.topic,
+        member_ids: row.member_ids,
+        member_contents: row.member_contents,
+        time_range_start: row.time_start,
+        time_range_end: row.time_end,
+    }));
+}
+/**
+ * Session-clustered variant: groups un-consolidated memories within a
+ * sliding 6-hour observed_at window for the same user. The "topic" field
+ * returned is a synthetic label `session-<bucket-iso>` so downstream
+ * storage layout is unchanged. Doesn't depend on topic_abstraction —
+ * works on raw observed_at, available since AM ingest start.
+ */
+async function findUnconsolidatedSessionClusters(pool, userId, minSize) {
+    const result = await pool.query(`SELECT 'session-' || to_char(date_trunc('hour', observed_at - INTERVAL '0 hours'), 'YYYY-MM-DD"T"HH24') AS topic,
+            array_agg(id ORDER BY observed_at) AS member_ids,
+            array_agg(content ORDER BY observed_at) AS member_contents,
+            MIN(observed_at) AS time_start,
+            MAX(observed_at) AS time_end,
+            COUNT(*) AS n
+     FROM memories
+     WHERE user_id = $1
+       AND deleted_at IS NULL
+       AND expired_at IS NULL
+       AND status = 'active'
+       AND workspace_id IS NULL
+       AND recap_id IS NULL
+     GROUP BY date_trunc('hour', observed_at)
+     HAVING COUNT(*) >= $2
+     ORDER BY MAX(observed_at) DESC
+     LIMIT 32`, [userId, minSize]);
+    return result.rows.map((row) => ({
+        topic: row.topic,
+        member_ids: row.member_ids,
+        member_contents: row.member_contents,
+        time_range_start: row.time_start,
+        time_range_end: row.time_end,
+    }));
+}
+/**
+ * Insert a new episode and mark its member memories as consolidated.
+ * Wrapped in a transaction so member-flag updates can't drift from the
+ * episode insert.
+ */
+export async function storeRecap(pool, input) {
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN');
+        const insertResult = await client.query(`INSERT INTO recaps
+        (user_id, recap_text, recap_embedding, topic,
+         member_memory_ids, member_count,
+         time_range_start, time_range_end)
+       VALUES ($1, $2, $3::vector, $4, $5::uuid[], $6, $7, $8)
+       RETURNING id`, [
+            input.userId,
+            input.recapText,
+            JSON.stringify(input.recapEmbedding),
+            input.topic,
+            input.memberMemoryIds,
+            input.memberMemoryIds.length,
+            input.timeRangeStart,
+            input.timeRangeEnd,
+        ]);
+        const episodeId = insertResult.rows[0].id;
+        if (input.memberMemoryIds.length > 0) {
+            await client.query(`UPDATE memories
+         SET recap_id = $1
+         WHERE id = ANY($2::uuid[]) AND user_id = $3`, [episodeId, input.memberMemoryIds, input.userId]);
+        }
+        await client.query('COMMIT');
+        return episodeId;
+    }
+    catch (err) {
+        await client.query('ROLLBACK').catch(() => undefined);
+        throw err;
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * Find episode candidates by embedding similarity. Used as a dedicated
+ * RRF channel at retrieval.
+ */
+export async function findRecapCandidates(pool, userId, queryEmbedding, limit) {
+    const result = await pool.query(`SELECT id, user_id, recap_text, recap_embedding::text AS recap_embedding,
+            topic, member_count,
+            1 - (recap_embedding <=> $2::vector) AS similarity
+     FROM recaps
+     WHERE user_id = $1
+       AND workspace_id IS NULL
+     ORDER BY recap_embedding <=> $2::vector
+     LIMIT $3`, [userId, JSON.stringify(queryEmbedding), limit]);
+    return result.rows.map((row) => ({
+        id: row.id,
+        user_id: row.user_id,
+        recap_text: row.recap_text,
+        recap_embedding: parsePgVector(row.recap_embedding),
+        topic: row.topic,
+        member_count: Number(row.member_count),
+        similarity: Number(row.similarity),
+    }));
+}

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

@@ -0,0 +1,48 @@
+/**
+ * Child representation storage for dual-write memory cells.
+ * Parent `memories` rows remain the packaging unit; atomic facts and foresight
+ * rows provide retrieval-optimized child views over the same memory.
+ */
+import pg from 'pg';
+import { type AtomicFactRow, type AtomicFactType, type ForesightRow, type ForesightType, type SearchResult } from './repository-types.js';
+type Queryable = Pick<pg.Pool, 'query'> | pg.PoolClient;
+export interface StoreAtomicFactInput {
+    userId: string;
+    parentMemoryId: string;
+    factText: string;
+    embedding: number[];
+    factType: AtomicFactType;
+    importance: number;
+    sourceSite: string;
+    sourceUrl?: string;
+    episodeId?: string;
+    keywords?: string;
+    metadata?: Record<string, unknown>;
+    /** Phase 5: workspace scope for workspace-originated facts. NULL for user-scoped. */
+    workspaceId?: string;
+    agentId?: string;
+}
+export interface StoreForesightInput {
+    userId: string;
+    parentMemoryId: string;
+    content: string;
+    embedding: number[];
+    foresightType: ForesightType;
+    sourceSite: string;
+    sourceUrl?: string;
+    episodeId?: string;
+    metadata?: Record<string, unknown>;
+    validFrom?: Date;
+    validTo?: Date | null;
+    /** Phase 5: workspace scope for workspace-originated foresight. NULL for user-scoped. */
+    workspaceId?: string;
+    agentId?: string;
+}
+export declare function storeAtomicFacts(queryable: Queryable, facts: StoreAtomicFactInput[]): Promise<string[]>;
+export declare function replaceAtomicFactsForMemory(queryable: Queryable, userId: string, parentMemoryId: string, facts: StoreAtomicFactInput[]): Promise<string[]>;
+export declare function listAtomicFactsForMemory(queryable: Queryable, userId: string, parentMemoryId: string): Promise<AtomicFactRow[]>;
+export declare function storeForesight(queryable: Queryable, foresight: StoreForesightInput[]): Promise<string[]>;
+export declare function replaceForesightForMemory(queryable: Queryable, userId: string, parentMemoryId: string, foresight: StoreForesightInput[]): Promise<string[]>;
+export declare function listForesightForMemory(queryable: Queryable, userId: string, parentMemoryId: string): Promise<ForesightRow[]>;
+export declare function searchAtomicFactsHybrid(pool: pg.Pool, userId: string, queryText: string, queryEmbedding: number[], limit: number, sourceSite?: string, referenceTime?: Date): Promise<SearchResult[]>;
+export {};