@atomicmemory/core 1.0.0

package/dist/db/passport-feed-repository.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Phase D — passport feed grouped data-layer query.
+ *
+ * Returns one row per documentId-with-memories (via `GROUP BY
+ * raw_document_id`) plus 1:1 standalone-memory rows (memories whose
+ * `raw_document_id IS NULL`), ordered by a unified
+ * `(sort_at DESC, sort_id DESC)` cursor.
+ *
+ * The webapp's `/api/context/passport` route consumes this as the
+ * memory-feed stream of its server-side two-stream merge — no
+ * webapp-side dedupe, no possibility of a single document spanning
+ * pages, no chunk-budget heuristic. A document with N memories
+ * appears EXACTLY once on the page that contains its latest
+ * chunk.
+ *
+ * Internal columns (embeddings, audit fields, internal metadata) are
+ * NEVER returned by this repository — the SELECT enumerates only the
+ * public projection that the route formatter then ships on the wire.
+ *
+ * Standard `+1 over-fetch` pagination: the route slices the extra
+ * row off and encodes its `(sort_at, sort_id)` as `next_cursor`.
+ */
+import type pg from 'pg';
+import { type DocumentListCursor } from './document-list-cursor.js';
+export interface PassportFeedDocumentGroupedRow {
+    kind: 'document_grouped';
+    documentId: string;
+    sortAt: Date;
+    sortId: string;
+    representative: {
+        id: string;
+        content: string;
+        createdAt: Date;
+        sourceSite: string | null;
+    };
+    chunkCount: number;
+    rawStorageStatus: string;
+    extractionStatus: string;
+    semanticIndexStatus: string;
+    lastError: unknown;
+    displayName: string | null;
+    mimeType: string | null;
+    /**
+     * Phase 7a wire widening (rev-2 §2): grouped rows carry the
+     * document's `storage_provider` + INTERNAL `raw_storage_metadata`
+     * blob. The route formatter projects them through
+     * `formatPublicRawStorageMetadata` + `getDeleteSemantics` before
+     * emitting to the wire — internal `upload_result`, AES-GCM
+     * `nonce`/`tag`/`key_id`, etc. are stripped at the formatter
+     * boundary.
+     */
+    storageProvider: string | null;
+    rawStorageMetadata: Record<string, unknown>;
+}
+export interface PassportFeedStandaloneMemoryRow {
+    kind: 'standalone_memory';
+    sortAt: Date;
+    sortId: string;
+    memory: {
+        id: string;
+        content: string;
+        createdAt: Date;
+        sourceSite: string | null;
+    };
+}
+export type PassportFeedRow = PassportFeedDocumentGroupedRow | PassportFeedStandaloneMemoryRow;
+export interface ListPassportFeedInput {
+    userId: string;
+    limit: number;
+    cursor: DocumentListCursor | null;
+}
+export interface ListPassportFeedResult {
+    rows: PassportFeedRow[];
+    nextCursor: string | null;
+}
+/**
+ * Phase D — main passport-feed query. Single SQL statement; one
+ * UNION ALL across:
+ *   (A) one row per documentId with at least one non-deleted memory.
+ *       Grouped via `GROUP BY raw_document_id`; the latest chunk in
+ *       each group is the representative (`(created_at DESC, id DESC)`
+ *       picks it via `ARRAY_AGG(...)`)[1]). Joined to
+ *       `raw_documents` for the Phase B status envelope; the join
+ *       also enforces `deleted_at IS NULL` + `user_id` match so
+ *       cross-user / soft-deleted documents fall out.
+ *   (B) one row per non-deleted memory whose `raw_document_id IS NULL`.
+ * Sort by `(sort_at DESC, sort_id DESC)` over the unioned rows; the
+ * route then slices the `+1` over-fetch and encodes the last consumed
+ * row's tuple as `next_cursor`.
+ */
+export declare function listPassportFeed(pool: pg.Pool, input: ListPassportFeedInput): Promise<ListPassportFeedResult>;

package/dist/db/passport-feed-repository.js

@@ -0,0 +1,198 @@
+/**
+ * Phase D — passport feed grouped data-layer query.
+ *
+ * Returns one row per documentId-with-memories (via `GROUP BY
+ * raw_document_id`) plus 1:1 standalone-memory rows (memories whose
+ * `raw_document_id IS NULL`), ordered by a unified
+ * `(sort_at DESC, sort_id DESC)` cursor.
+ *
+ * The webapp's `/api/context/passport` route consumes this as the
+ * memory-feed stream of its server-side two-stream merge — no
+ * webapp-side dedupe, no possibility of a single document spanning
+ * pages, no chunk-budget heuristic. A document with N memories
+ * appears EXACTLY once on the page that contains its latest
+ * chunk.
+ *
+ * Internal columns (embeddings, audit fields, internal metadata) are
+ * NEVER returned by this repository — the SELECT enumerates only the
+ * public projection that the route formatter then ships on the wire.
+ *
+ * Standard `+1 over-fetch` pagination: the route slices the extra
+ * row off and encodes its `(sort_at, sort_id)` as `next_cursor`.
+ */
+import { encodeListCursor, } from './document-list-cursor.js';
+const PASSPORT_FEED_DEFAULT_LIMIT = 50;
+const PASSPORT_FEED_MAX_LIMIT = 100;
+/**
+ * Phase D — main passport-feed query. Single SQL statement; one
+ * UNION ALL across:
+ *   (A) one row per documentId with at least one non-deleted memory.
+ *       Grouped via `GROUP BY raw_document_id`; the latest chunk in
+ *       each group is the representative (`(created_at DESC, id DESC)`
+ *       picks it via `ARRAY_AGG(...)`)[1]). Joined to
+ *       `raw_documents` for the Phase B status envelope; the join
+ *       also enforces `deleted_at IS NULL` + `user_id` match so
+ *       cross-user / soft-deleted documents fall out.
+ *   (B) one row per non-deleted memory whose `raw_document_id IS NULL`.
+ * Sort by `(sort_at DESC, sort_id DESC)` over the unioned rows; the
+ * route then slices the `+1` over-fetch and encodes the last consumed
+ * row's tuple as `next_cursor`.
+ */
+export async function listPassportFeed(pool, input) {
+    const limit = clampLimit(input.limit);
+    const overFetch = limit + 1;
+    const params = [input.userId, overFetch];
+    const cursorClauseGrouped = buildCursorClause(input.cursor, params, 'grouped');
+    const cursorClauseStandalone = buildCursorClause(input.cursor, params, 'standalone');
+    const sql = `
+    WITH memory_groups AS (
+      SELECT m.raw_document_id AS document_id,
+             MAX(m.created_at) AS sort_at,
+             (ARRAY_AGG(m.id          ORDER BY m.created_at DESC, m.id DESC))[1] AS sort_id,
+             (ARRAY_AGG(m.id          ORDER BY m.created_at DESC, m.id DESC))[1] AS rep_id,
+             (ARRAY_AGG(m.content     ORDER BY m.created_at DESC, m.id DESC))[1] AS rep_content,
+             (ARRAY_AGG(m.created_at  ORDER BY m.created_at DESC, m.id DESC))[1] AS rep_created_at,
+             (ARRAY_AGG(m.source_site ORDER BY m.created_at DESC, m.id DESC))[1] AS rep_source_site,
+             COUNT(*)::INT AS chunk_count
+        FROM memories m
+       WHERE m.user_id = $1
+         AND m.deleted_at IS NULL
+         AND m.raw_document_id IS NOT NULL
+       GROUP BY m.raw_document_id
+    )
+    SELECT 'document_grouped'::text AS kind,
+           mg.document_id::text     AS document_id,
+           mg.sort_at, mg.sort_id::text AS sort_id,
+           mg.rep_id::text          AS rep_id,
+           mg.rep_content, mg.rep_created_at, mg.rep_source_site,
+           mg.chunk_count,
+           rd.raw_storage_status, rd.extraction_status, rd.semantic_index_status,
+           rd.last_error, rd.display_name, rd.mime_type,
+           rd.storage_provider, rd.raw_storage_metadata
+      FROM memory_groups mg
+      JOIN raw_documents rd
+        ON rd.id = mg.document_id
+       AND rd.user_id = $1
+       AND rd.deleted_at IS NULL
+     WHERE ${cursorClauseGrouped}
+    UNION ALL
+    SELECT 'standalone_memory'::text AS kind,
+           NULL                       AS document_id,
+           m.created_at               AS sort_at,
+           m.id::text                 AS sort_id,
+           m.id::text                 AS rep_id,
+           m.content                  AS rep_content,
+           m.created_at               AS rep_created_at,
+           m.source_site              AS rep_source_site,
+           1                          AS chunk_count,
+           NULL::text                 AS raw_storage_status,
+           NULL::text                 AS extraction_status,
+           NULL::text                 AS semantic_index_status,
+           NULL::jsonb                AS last_error,
+           NULL::text                 AS display_name,
+           NULL::text                 AS mime_type,
+           NULL::text                 AS storage_provider,
+           NULL::jsonb                AS raw_storage_metadata
+      FROM memories m
+     WHERE m.user_id = $1
+       AND m.deleted_at IS NULL
+       AND m.raw_document_id IS NULL
+       AND ${cursorClauseStandalone}
+    ORDER BY sort_at DESC, sort_id DESC
+    LIMIT $2
+  `;
+    const result = await pool.query(sql, params);
+    const all = result.rows.map(toPassportFeedRow);
+    return slicePageWithCursor(all, limit);
+}
+function clampLimit(raw) {
+    if (raw === undefined || !Number.isFinite(raw))
+        return PASSPORT_FEED_DEFAULT_LIMIT;
+    return Math.max(1, Math.min(PASSPORT_FEED_MAX_LIMIT, Math.floor(raw)));
+}
+/**
+ * Build the cursor predicate fragment for one branch of the UNION.
+ * Returns a SQL boolean expression that evaluates to TRUE when the
+ * caller did not supply a cursor (first page) or when the row's
+ * `(sort_at, sort_id)` is strictly less than the supplied cursor.
+ *
+ * Each branch references different columns (`mg.sort_at` for the
+ * grouped CTE; `m.created_at` for standalone memories), so we
+ * assemble the fragment per-branch and append fresh parameter
+ * placeholders to `params` for each branch's bind sites.
+ */
+function buildCursorClause(cursor, params, branch) {
+    if (cursor === null)
+        return 'TRUE';
+    params.push(cursor.sortAt, cursor.sortId);
+    const atIdx = params.length - 1;
+    const idIdx = params.length;
+    if (branch === 'grouped') {
+        return `(mg.sort_at, mg.sort_id::text) < ($${atIdx}::timestamptz, $${idIdx}::text)`;
+    }
+    return `(m.created_at, m.id::text) < ($${atIdx}::timestamptz, $${idIdx}::text)`;
+}
+/** Map one Postgres row to the kind-discriminated public shape. */
+function toPassportFeedRow(row) {
+    const kind = row.kind;
+    if (kind === 'document_grouped') {
+        return toDocumentGroupedRow(row);
+    }
+    return toStandaloneMemoryRow(row);
+}
+function toDocumentGroupedRow(row) {
+    return {
+        kind: 'document_grouped',
+        documentId: row.document_id,
+        sortAt: row.sort_at,
+        sortId: row.sort_id,
+        representative: {
+            id: row.rep_id,
+            content: row.rep_content,
+            createdAt: row.rep_created_at,
+            sourceSite: row.rep_source_site ?? null,
+        },
+        chunkCount: Number(row.chunk_count),
+        rawStorageStatus: row.raw_storage_status,
+        extractionStatus: row.extraction_status,
+        semanticIndexStatus: row.semantic_index_status,
+        lastError: row.last_error,
+        displayName: row.display_name ?? null,
+        mimeType: row.mime_type ?? null,
+        storageProvider: row.storage_provider ?? null,
+        rawStorageMetadata: row.raw_storage_metadata ?? {},
+    };
+}
+function toStandaloneMemoryRow(row) {
+    return {
+        kind: 'standalone_memory',
+        sortAt: row.sort_at,
+        sortId: row.sort_id,
+        memory: {
+            id: row.rep_id,
+            content: row.rep_content,
+            createdAt: row.rep_created_at,
+            sourceSite: row.rep_source_site ?? null,
+        },
+    };
+}
+/**
+ * Cursor-aware page slicer. The repository over-fetches by one row;
+ * if we got the full `limit + 1`, the last consumed row's
+ * `(sort_at, sort_id)` becomes the next cursor. Otherwise the page
+ * exhausts the stream and `nextCursor === null`.
+ */
+function slicePageWithCursor(candidates, limit) {
+    if (candidates.length <= limit) {
+        return { rows: candidates, nextCursor: null };
+    }
+    const rows = candidates.slice(0, limit);
+    const last = rows[rows.length - 1];
+    const sortAt = last.sortAt instanceof Date
+        ? last.sortAt.toISOString()
+        : String(last.sortAt);
+    return {
+        rows,
+        nextCursor: encodeListCursor({ sortAt, sortId: last.sortId }),
+    };
+}

package/dist/db/pg-episode-store.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Postgres-backed EpisodeStore implementation.
+ */
+import type pg from 'pg';
+import type { EpisodeStore } from './stores.js';
+export declare class PgEpisodeStore implements EpisodeStore {
+    private pool;
+    constructor(pool: pg.Pool);
+    storeEpisode(input: {
+        userId: string;
+        content: string;
+        sourceSite: string;
+        sourceUrl?: string;
+        sessionId?: string;
+        workspaceId?: string;
+        agentId?: string;
+    }): Promise<string>;
+    getEpisode(id: string): Promise<import("./repository-types.js").EpisodeRow | null>;
+}

package/dist/db/pg-episode-store.js

@@ -0,0 +1,17 @@
+/**
+ * Postgres-backed EpisodeStore implementation.
+ */
+import { getEpisode } from './repository-read.js';
+import { storeEpisode } from './repository-write.js';
+export class PgEpisodeStore {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async storeEpisode(input) {
+        return storeEpisode(this.pool, input);
+    }
+    async getEpisode(id) {
+        return getEpisode(this.pool, id);
+    }
+}

package/dist/db/pg-link-store.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Postgres-backed SemanticLinkStore implementation.
+ */
+import type pg from 'pg';
+import type { SemanticLinkStore } from './stores.js';
+import { type MemoryLink } from './repository-links.js';
+export declare class PgSemanticLinkStore implements SemanticLinkStore {
+    private pool;
+    constructor(pool: pg.Pool);
+    createLinks(links: MemoryLink[]): Promise<number>;
+    findLinkCandidates(userId: string, embedding: number[], threshold: number, excludeId: string, limit?: number): Promise<{
+        id: string;
+        similarity: number;
+    }[]>;
+    findLinkedMemoryIds(memoryIds: string[], excludeIds: Set<string>, limit: number): Promise<string[]>;
+    countLinks(): Promise<number>;
+}

package/dist/db/pg-link-store.js

@@ -0,0 +1,14 @@
+/**
+ * Postgres-backed SemanticLinkStore implementation.
+ */
+import { createLinks, findLinkCandidates, findLinkedMemoryIds, countLinks, } from './repository-links.js';
+export class PgSemanticLinkStore {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async createLinks(links) { return createLinks(this.pool, links); }
+    async findLinkCandidates(userId, embedding, threshold, excludeId, limit = 10) { return findLinkCandidates(this.pool, userId, embedding, threshold, excludeId, limit); }
+    async findLinkedMemoryIds(memoryIds, excludeIds, limit) { return findLinkedMemoryIds(this.pool, memoryIds, excludeIds, limit); }
+    async countLinks() { return countLinks(this.pool); }
+}

package/dist/db/pg-memory-store.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Postgres-backed MemoryStore implementation.
+ * Delegates to existing repository-read.ts and repository-write.ts functions.
+ */
+import type pg from 'pg';
+import type { MemoryStore, StoreMemoryInput } from './stores.js';
+import type { CanonicalMemoryObjectLineage } from './repository-types.js';
+export declare class PgMemoryStore implements MemoryStore {
+    private pool;
+    /**
+     * Optional Phase-3 raw-content adapter, threaded through `deleteAll`
+     * so the wipe path also cleans up managed-blob bytes. `null` for
+     * pointer-only deployments and most tests; no fallback.
+     */
+    private readonly rawContentStore;
+    /**
+     * Phase 4a per-row dispatch registry. See `MemoryRepository` for the
+     * thread-through rationale; same fallback behavior — absent registry
+     * resolves to `singleStoreRegistry(rawContentStore)` inside
+     * `repository-write.deleteAll`.
+     */
+    private readonly storeRegistry;
+    constructor(pool: pg.Pool, options?: {
+        rawContentStore?: import('../storage/raw-content-store.js').RawContentStore | null;
+        storeRegistry?: import('../storage/store-registry.js').RawContentStoreRegistry;
+    });
+    storeMemory(input: StoreMemoryInput): Promise<string>;
+    getMemory(id: string, userId?: string): Promise<import("./repository-types.js").MemoryRow | null>;
+    getMemoryIncludingDeleted(id: string, userId?: string): Promise<import("./repository-types.js").MemoryRow | null>;
+    listMemories(userId: string, limit?: number, offset?: number, sourceSite?: string, episodeId?: string): Promise<import("./repository-types.js").MemoryRow[]>;
+    softDeleteMemory(userId: string, id: string): Promise<void>;
+    updateMemoryContent(userId: string, id: string, content: string, embedding: number[], importance: number, keywords?: string, trustScore?: number): Promise<void>;
+    updateMemoryMetadata(userId: string, id: string, metadata: Record<string, unknown>): Promise<void>;
+    expireMemory(userId: string, id: string): Promise<void>;
+    touchMemory(id: string): Promise<void>;
+    countMemories(userId?: string): Promise<number>;
+    getMemoryStats(userId: string): Promise<{
+        count: number;
+        avgImportance: number;
+        sourceDistribution: Record<string, number>;
+    }>;
+    deleteBySource(userId: string, sourceSite: string): Promise<import("./repository-document-delete.js").DeleteBySourceResult>;
+    deleteAll(userId?: string): Promise<void>;
+    backdateMemories(ids: string[], timestamp: Date): Promise<void>;
+    updateOpinionConfidence(userId: string, memoryId: string, newConfidence: number): Promise<void>;
+    countNeedsClarification(userId: string): Promise<number>;
+    storeCanonicalMemoryObject(input: {
+        userId: string;
+        objectFamily: 'ingested_fact';
+        payloadFormat?: string;
+        canonicalPayload: {
+            factText: string;
+            factType: string;
+            headline: string;
+            keywords: string[];
+        };
+        provenance: {
+            episodeId: string | null;
+            sourceSite: string;
+            sourceUrl: string;
+        };
+        observedAt?: Date;
+        lineage: CanonicalMemoryObjectLineage;
+    }): Promise<string>;
+    getMemoryInWorkspace(id: string, workspaceId: string, callerAgentId?: string): Promise<import("./repository-types.js").MemoryRow | null>;
+    listMemoriesInWorkspace(workspaceId: string, limit?: number, offset?: number, callerAgentId?: string): Promise<import("./repository-types.js").MemoryRow[]>;
+    softDeleteMemoryInWorkspace(id: string, workspaceId: string): Promise<void>;
+}

package/dist/db/pg-memory-store.js

@@ -0,0 +1,53 @@
+/**
+ * Postgres-backed MemoryStore implementation.
+ * Delegates to existing repository-read.ts and repository-write.ts functions.
+ */
+import { getMemory, getMemoryInWorkspace, getMemoryStats, listMemories, listMemoriesInWorkspace, countMemories, countNeedsClarification, } from './repository-read.js';
+import { backdateMemories, deleteAll, expireMemory, softDeleteMemory, softDeleteMemoryInWorkspace, storeCanonicalMemoryObject, storeMemory, touchMemory, updateMemoryContent, updateMemoryMetadata, updateOpinionConfidence, } from './repository-write.js';
+import { deleteBySource } from './repository-document-delete.js';
+export class PgMemoryStore {
+    pool;
+    /**
+     * Optional Phase-3 raw-content adapter, threaded through `deleteAll`
+     * so the wipe path also cleans up managed-blob bytes. `null` for
+     * pointer-only deployments and most tests; no fallback.
+     */
+    rawContentStore;
+    /**
+     * Phase 4a per-row dispatch registry. See `MemoryRepository` for the
+     * thread-through rationale; same fallback behavior — absent registry
+     * resolves to `singleStoreRegistry(rawContentStore)` inside
+     * `repository-write.deleteAll`.
+     */
+    storeRegistry;
+    constructor(pool, options = {}) {
+        this.pool = pool;
+        this.rawContentStore = options.rawContentStore ?? null;
+        this.storeRegistry = options.storeRegistry;
+    }
+    async storeMemory(input) { return storeMemory(this.pool, input); }
+    async getMemory(id, userId) { return getMemory(this.pool, id, userId, false); }
+    async getMemoryIncludingDeleted(id, userId) { return getMemory(this.pool, id, userId, true); }
+    async listMemories(userId, limit = 20, offset = 0, sourceSite, episodeId) { return listMemories(this.pool, userId, limit, offset, sourceSite, episodeId); }
+    async softDeleteMemory(userId, id) { return softDeleteMemory(this.pool, userId, id); }
+    async updateMemoryContent(userId, id, content, embedding, importance, keywords, trustScore) { return updateMemoryContent(this.pool, userId, id, content, embedding, importance, keywords, trustScore); }
+    async updateMemoryMetadata(userId, id, metadata) { return updateMemoryMetadata(this.pool, userId, id, metadata); }
+    async expireMemory(userId, id) { return expireMemory(this.pool, userId, id); }
+    async touchMemory(id) { return touchMemory(this.pool, id); }
+    async countMemories(userId) { return countMemories(this.pool, userId); }
+    async getMemoryStats(userId) { return getMemoryStats(this.pool, userId); }
+    async deleteBySource(userId, sourceSite) { return deleteBySource(this.pool, userId, sourceSite); }
+    async deleteAll(userId) {
+        return deleteAll(this.pool, userId, {
+            rawContentStore: this.rawContentStore,
+            storeRegistry: this.storeRegistry,
+        });
+    }
+    async backdateMemories(ids, timestamp) { return backdateMemories(this.pool, ids, timestamp); }
+    async updateOpinionConfidence(userId, memoryId, newConfidence) { return updateOpinionConfidence(this.pool, userId, memoryId, newConfidence); }
+    async countNeedsClarification(userId) { return countNeedsClarification(this.pool, userId); }
+    async storeCanonicalMemoryObject(input) { return storeCanonicalMemoryObject(this.pool, input); }
+    async getMemoryInWorkspace(id, workspaceId, callerAgentId) { return getMemoryInWorkspace(this.pool, id, workspaceId, callerAgentId); }
+    async listMemoriesInWorkspace(workspaceId, limit = 20, offset = 0, callerAgentId) { return listMemoriesInWorkspace(this.pool, workspaceId, limit, offset, callerAgentId); }
+    async softDeleteMemoryInWorkspace(id, workspaceId) { return softDeleteMemoryInWorkspace(this.pool, id, workspaceId); }
+}

package/dist/db/pg-recap-store.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Postgres-backed RecapStore (Sprint 3 v1). Delegates to repository-recaps.
+ */
+import type pg from 'pg';
+import type { RecapStore } from './stores.js';
+import { type StoreRecapInput } from './repository-recaps.js';
+export declare class PgRecapStore implements RecapStore {
+    private pool;
+    constructor(pool: pg.Pool);
+    findUnconsolidatedClusters(userId: string, minSize: number, pivot?: 'topic' | 'session'): Promise<import("./repository-recaps.js").UnconsolidatedCluster[]>;
+    storeRecap(input: StoreRecapInput): Promise<string>;
+    findRecapCandidates(userId: string, queryEmbedding: number[], limit: number): Promise<import("./repository-recaps.js").RecapRow[]>;
+}

package/dist/db/pg-recap-store.js

@@ -0,0 +1,19 @@
+/**
+ * Postgres-backed RecapStore (Sprint 3 v1). Delegates to repository-recaps.
+ */
+import { findRecapCandidates, findUnconsolidatedClusters, storeRecap, } from './repository-recaps.js';
+export class PgRecapStore {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async findUnconsolidatedClusters(userId, minSize, pivot = 'topic') {
+        return findUnconsolidatedClusters(this.pool, userId, minSize, pivot);
+    }
+    async storeRecap(input) {
+        return storeRecap(this.pool, input);
+    }
+    async findRecapCandidates(userId, queryEmbedding, limit) {
+        return findRecapCandidates(this.pool, userId, queryEmbedding, limit);
+    }
+}

package/dist/db/pg-representation-store.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Postgres-backed RepresentationStore implementation.
+ * Manages atomic facts and foresight projections.
+ */
+import type pg from 'pg';
+import type { RepresentationStore } from './stores.js';
+import { type StoreAtomicFactInput, type StoreForesightInput } from './repository-representations.js';
+export declare class PgRepresentationStore implements RepresentationStore {
+    private pool;
+    constructor(pool: pg.Pool);
+    storeAtomicFacts(facts: StoreAtomicFactInput[]): Promise<string[]>;
+    storeForesight(entries: StoreForesightInput[]): Promise<string[]>;
+    listAtomicFactsForMemory(userId: string, parentMemoryId: string): Promise<import("./repository-types.js").AtomicFactRow[]>;
+    listForesightForMemory(userId: string, parentMemoryId: string): Promise<import("./repository-types.js").ForesightRow[]>;
+    replaceAtomicFactsForMemory(userId: string, parentMemoryId: string, facts: StoreAtomicFactInput[]): Promise<string[]>;
+    replaceForesightForMemory(userId: string, parentMemoryId: string, entries: StoreForesightInput[]): Promise<string[]>;
+}

package/dist/db/pg-representation-store.js

@@ -0,0 +1,17 @@
+/**
+ * Postgres-backed RepresentationStore implementation.
+ * Manages atomic facts and foresight projections.
+ */
+import { listAtomicFactsForMemory, listForesightForMemory, replaceAtomicFactsForMemory, replaceForesightForMemory, storeAtomicFacts, storeForesight, } from './repository-representations.js';
+export class PgRepresentationStore {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async storeAtomicFacts(facts) { return storeAtomicFacts(this.pool, facts); }
+    async storeForesight(entries) { return storeForesight(this.pool, entries); }
+    async listAtomicFactsForMemory(userId, parentMemoryId) { return listAtomicFactsForMemory(this.pool, userId, parentMemoryId); }
+    async listForesightForMemory(userId, parentMemoryId) { return listForesightForMemory(this.pool, userId, parentMemoryId); }
+    async replaceAtomicFactsForMemory(userId, parentMemoryId, facts) { return replaceAtomicFactsForMemory(this.pool, userId, parentMemoryId, facts); }
+    async replaceForesightForMemory(userId, parentMemoryId, entries) { return replaceForesightForMemory(this.pool, userId, parentMemoryId, entries); }
+}

package/dist/db/pg-search-store.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Postgres-backed SearchStore implementation.
+ * Delegates to repository-read.ts (vector/hybrid/keyword search) and
+ * repository-links.ts (fetchMemoriesByIds).
+ */
+import type pg from 'pg';
+import type { AgentScope } from './repository-types.js';
+import type { SearchStore } from './stores.js';
+export declare class PgSearchStore implements SearchStore {
+    private pool;
+    constructor(pool: pg.Pool);
+    searchSimilar(userId: string, queryEmbedding: number[], limit: number, sourceSite?: string, referenceTime?: Date): Promise<import("./repository-types.js").SearchResult[]>;
+    searchHybrid(userId: string, queryText: string, queryEmbedding: number[], limit: number, sourceSite?: string, referenceTime?: Date): Promise<import("./repository-types.js").SearchResult[]>;
+    searchKeyword(userId: string, queryText: string, limit: number, sourceSite?: string): Promise<import("./repository-types.js").SearchResult[]>;
+    searchAtomicFactsHybrid(userId: string, queryText: string, queryEmbedding: number[], limit: number, sourceSite?: string, referenceTime?: Date): Promise<import("./repository-types.js").SearchResult[]>;
+    findNearDuplicates(userId: string, embedding: number[], threshold: number, limit?: number): Promise<import("./repository-vector-search.js").CandidateRow[]>;
+    findKeywordCandidates(userId: string, keywords: string[], limit?: number, includeExpired?: boolean): Promise<any[]>;
+    findTopicCandidates(userId: string, queryEmbedding: number[], limit: number): Promise<{
+        id: string;
+        content: string;
+        topic_abstraction: string;
+        importance: number;
+        similarity: number;
+    }[]>;
+    findTemporalNeighbors(userId: string, anchorTimestamps: Date[], queryEmbedding: number[], windowMinutes: number, excludeIds: Set<string>, limit: number, referenceTime?: Date): Promise<import("./repository-types.js").SearchResult[]>;
+    fetchMemoriesByIds(userId: string, ids: string[], queryEmbedding: number[], referenceTime?: Date, includeExpired?: boolean): Promise<import("./repository-types.js").SearchResult[]>;
+    searchSimilarInWorkspace(workspaceId: string, queryEmbedding: number[], limit: number, agentScope?: AgentScope, callerAgentId?: string, referenceTime?: Date): Promise<import("./repository-types.js").SearchResult[]>;
+    findNearDuplicatesInWorkspace(workspaceId: string, embedding: number[], threshold: number, limit?: number, agentScope?: AgentScope, callerAgentId?: string): Promise<import("./repository-vector-search.js").CandidateRow[]>;
+}

package/dist/db/pg-search-store.js

@@ -0,0 +1,47 @@
+/**
+ * Postgres-backed SearchStore implementation.
+ * Delegates to repository-read.ts (vector/hybrid/keyword search) and
+ * repository-links.ts (fetchMemoriesByIds).
+ */
+import { findKeywordCandidates, findNearDuplicates, findNearDuplicatesInWorkspace, findTemporalNeighbors, findTopicCandidates, searchHybridSimilar, searchKeywordSimilar, searchSimilar, searchSimilarInWorkspace, } from './repository-read.js';
+import { searchAtomicFactsHybrid } from './repository-representations.js';
+import { fetchMemoriesByIds } from './repository-links.js';
+export class PgSearchStore {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async searchSimilar(userId, queryEmbedding, limit, sourceSite, referenceTime) {
+        return searchSimilar(this.pool, userId, queryEmbedding, limit, sourceSite, referenceTime);
+    }
+    async searchHybrid(userId, queryText, queryEmbedding, limit, sourceSite, referenceTime) {
+        return searchHybridSimilar(this.pool, userId, queryText, queryEmbedding, limit, sourceSite, referenceTime);
+    }
+    async searchKeyword(userId, queryText, limit, sourceSite) {
+        return searchKeywordSimilar(this.pool, userId, queryText, limit, sourceSite);
+    }
+    async searchAtomicFactsHybrid(userId, queryText, queryEmbedding, limit, sourceSite, referenceTime) {
+        return searchAtomicFactsHybrid(this.pool, userId, queryText, queryEmbedding, limit, sourceSite, referenceTime);
+    }
+    async findNearDuplicates(userId, embedding, threshold, limit = 3) {
+        return findNearDuplicates(this.pool, userId, embedding, threshold, limit);
+    }
+    async findKeywordCandidates(userId, keywords, limit = 5, includeExpired = false) {
+        return findKeywordCandidates(this.pool, userId, keywords, limit, includeExpired);
+    }
+    async findTopicCandidates(userId, queryEmbedding, limit) {
+        return findTopicCandidates(this.pool, userId, queryEmbedding, limit);
+    }
+    async findTemporalNeighbors(userId, anchorTimestamps, queryEmbedding, windowMinutes, excludeIds, limit, referenceTime) {
+        return findTemporalNeighbors(this.pool, userId, anchorTimestamps, queryEmbedding, windowMinutes, excludeIds, limit, referenceTime);
+    }
+    async fetchMemoriesByIds(userId, ids, queryEmbedding, referenceTime, includeExpired = false) {
+        return fetchMemoriesByIds(this.pool, userId, ids, queryEmbedding, referenceTime, includeExpired);
+    }
+    async searchSimilarInWorkspace(workspaceId, queryEmbedding, limit, agentScope = 'all', callerAgentId, referenceTime) {
+        return searchSimilarInWorkspace(this.pool, workspaceId, queryEmbedding, limit, agentScope, callerAgentId, referenceTime);
+    }
+    async findNearDuplicatesInWorkspace(workspaceId, embedding, threshold, limit = 3, agentScope = 'all', callerAgentId) {
+        return findNearDuplicatesInWorkspace(this.pool, workspaceId, embedding, threshold, limit, agentScope, callerAgentId);
+    }
+}

package/dist/db/pool.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Database connection pool for Postgres+pgvector.
+ * Reads DATABASE_URL from environment (loaded by dotenv-cli).
+ */
+export declare const pool: import("pg").Pool;

package/dist/db/pool.js

@@ -0,0 +1,21 @@
+/**
+ * Database connection pool for Postgres+pgvector.
+ * Reads DATABASE_URL from environment (loaded by dotenv-cli).
+ */
+import pg from 'pg';
+const DATABASE_URL = process.env.DATABASE_URL;
+if (!DATABASE_URL) {
+    throw new Error('DATABASE_URL environment variable is required');
+}
+// max=1 prevents pgvector HNSW index deadlocks: the index takes
+// AccessExclusiveLock during INSERT and AccessShareLock during SELECT.
+// With multiple connections these can deadlock across backend processes.
+export const pool = new pg.Pool({
+    connectionString: DATABASE_URL,
+    max: 1,
+    connectionTimeoutMillis: 30_000,
+    idleTimeoutMillis: 60_000,
+});
+pool.on('error', (err) => {
+    console.error('[pool] Unexpected idle client error:', err.message);
+});