@atomicmemory/core 1.0.0

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

@@ -0,0 +1,30 @@
+/**
+ * Repository for typed cross-agent memory links.
+ * Stores and queries endorsement, contradiction, elaboration, and correction
+ * links between memories from different agents.
+ */
+import pg from 'pg';
+export type LinkType = 'similarity' | 'endorsement' | 'contradiction' | 'elaboration' | 'correction';
+export interface MemoryLink {
+    id: string;
+    source_memory_id: string;
+    target_memory_id: string;
+    link_type: LinkType;
+    source_agent_id: string | null;
+    target_agent_id: string | null;
+    created_at: Date;
+}
+export interface StoreLinkInput {
+    sourceMemoryId: string;
+    targetMemoryId: string;
+    linkType: LinkType;
+    sourceAgentId?: string | null;
+    targetAgentId?: string | null;
+}
+export declare class LinkRepository {
+    private pool;
+    constructor(pool: pg.Pool);
+    storeLink(input: StoreLinkInput): Promise<string>;
+    getLinksForMemory(memoryId: string): Promise<MemoryLink[]>;
+    getLinksForMemories(memoryIds: string[]): Promise<Map<string, MemoryLink[]>>;
+}

package/dist/db/link-repository.js

@@ -0,0 +1,54 @@
+/**
+ * Repository for typed cross-agent memory links.
+ * Stores and queries endorsement, contradiction, elaboration, and correction
+ * links between memories from different agents.
+ */
+export class LinkRepository {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async storeLink(input) {
+        const result = await this.pool.query(`INSERT INTO memory_links (source_memory_id, target_memory_id, link_type, source_agent_id, target_agent_id)
+       VALUES ($1, $2, $3, $4, $5)
+       ON CONFLICT (source_memory_id, target_memory_id, link_type) DO NOTHING
+       RETURNING id`, [
+            input.sourceMemoryId,
+            input.targetMemoryId,
+            input.linkType,
+            input.sourceAgentId ?? null,
+            input.targetAgentId ?? null,
+        ]);
+        return result.rows[0]?.id ?? '';
+    }
+    async getLinksForMemory(memoryId) {
+        const result = await this.pool.query(`SELECT * FROM memory_links
+       WHERE source_memory_id = $1 OR target_memory_id = $1
+       ORDER BY created_at DESC`, [memoryId]);
+        return result.rows;
+    }
+    async getLinksForMemories(memoryIds) {
+        if (memoryIds.length === 0)
+            return new Map();
+        const result = await this.pool.query(`SELECT * FROM memory_links
+       WHERE source_memory_id = ANY($1::uuid[]) OR target_memory_id = ANY($1::uuid[])
+       ORDER BY created_at DESC`, [memoryIds]);
+        const linksByMemory = new Map();
+        for (const row of result.rows) {
+            appendLink(linksByMemory, row.source_memory_id, row);
+            if (row.target_memory_id !== row.source_memory_id) {
+                appendLink(linksByMemory, row.target_memory_id, row);
+            }
+        }
+        return linksByMemory;
+    }
+}
+function appendLink(map, memoryId, link) {
+    const existing = map.get(memoryId);
+    if (existing) {
+        existing.push(link);
+    }
+    else {
+        map.set(memoryId, [link]);
+    }
+}

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

@@ -0,0 +1,163 @@
+/**
+ * @deprecated Phase 5 — use domain-facing store interfaces from `stores.ts` instead.
+ *
+ * This facade remains for two reasons:
+ * 1. `getPool()` is still needed by PPR and deferred-audn (raw pool access).
+ * 2. External helper modules (iterative-retrieval, agentic-retrieval, query-expansion,
+ *    etc.) still type their params as MemoryRepository. Those will be migrated
+ *    file-by-file to accept SearchStore/EntityStore.
+ *
+ * Remove this file once all consumers use stores.* and pool is exposed directly.
+ */
+import pg from 'pg';
+import type { AgentScope, CanonicalMemoryObjectLineage, StoreMemoryInput } from './repository-types.js';
+import { type MemoryLink } from './repository-links.js';
+import { type StoreAtomicFactInput, type StoreForesightInput } from './repository-representations.js';
+export type { AgentScope, AtomicFactRow, CanonicalMemoryObjectRow, EpisodeRow, ForesightRow, MemoryMetadata, MemoryRow, SearchResult, WorkspaceContext, } from './repository-types.js';
+export declare class MemoryRepository {
+    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. When supplied, the `deleteAll`
+     * wipe path routes each blob to the adapter registered for its
+     * `storage_provider` — historical legacy rows (e.g. `local-fs://`
+     * on a Filecoin-active deployment) go to the registered legacy
+     * adapter. When absent, `repository-write.deleteAll` falls back to
+     * `singleStoreRegistry(rawContentStore)` (the pre-Phase-4a behavior)
+     * so existing test/back-compat constructions stay working.
+     */
+    private readonly storeRegistry;
+    constructor(pool: pg.Pool, options?: {
+        rawContentStore?: import('../storage/raw-content-store.js').RawContentStore | null;
+        storeRegistry?: import('../storage/store-registry.js').RawContentStoreRegistry;
+    });
+    getPool(): import("pg").Pool;
+    storeEpisode(input: {
+        userId: string;
+        content: string;
+        sourceSite: string;
+        sourceUrl?: string;
+        sessionId?: string;
+        workspaceId?: string;
+        agentId?: string;
+    }): Promise<string>;
+    storeEpisodeWithClient(client: pg.PoolClient, input: {
+        userId: string;
+        content: string;
+        sourceSite: string;
+        sourceUrl?: string;
+        sessionId?: string;
+        workspaceId?: string;
+        agentId?: string;
+    }): Promise<string>;
+    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>;
+    getEpisode(id: string): Promise<import("./repository-types.js").EpisodeRow | null>;
+    storeMemory(input: StoreMemoryInput): Promise<string>;
+    storeMemoryWithClient(client: pg.PoolClient, 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>;
+    getMemoryIncludingDeletedWithClient(client: pg.PoolClient, 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[]>;
+    /** Fetch the text and timestamp for all non-deleted memories for a user's
+     * conversation. memories.column is `content`, not `text` — alias to the
+     * caller's expected shape.
+     *
+     * BEAM/AMB note: AMB encodes BEAM conversation_id INTO user_id, so each
+     * ingest creates a fresh episode_id but conversation memories accumulate
+     * under the same user_id. Match on user_id only so the reflect worker sees
+     * ALL memories from the active conversation, not just the last ingest. */
+    findByConversation(userId: string, conversationId: string): Promise<Array<{
+        id: string;
+        text: string;
+        observedAt: Date;
+    }>>;
+    listMemoriesInWorkspace(workspaceId: string, limit?: number, offset?: number, callerAgentId?: string): Promise<import("./repository-types.js").MemoryRow[]>;
+    getMemoryInWorkspace(id: string, workspaceId: string, callerAgentId?: string): Promise<import("./repository-types.js").MemoryRow | null>;
+    softDeleteMemoryInWorkspace(id: string, workspaceId: string): Promise<void>;
+    getMemoryStats(userId: string): Promise<{
+        count: number;
+        avgImportance: number;
+        sourceDistribution: Record<string, number>;
+    }>;
+    findMemoriesByNamespace(userId: string, namespace: string, limit?: number): Promise<import("./repository-types.js").MemoryRow[]>;
+    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[]>;
+    findNearDuplicatesWithClient(client: pg.PoolClient, 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[]>;
+    findKeywordCandidatesWithClient(client: pg.PoolClient, userId: string, keywords: string[], limit?: number): Promise<any[]>;
+    findTopicCandidates(userId: string, queryEmbedding: number[], limit: number): Promise<{
+        id: string;
+        content: string;
+        topic_abstraction: string;
+        importance: number;
+        similarity: number;
+    }[]>;
+    updateMemoryContent(userId: string, id: string, content: string, embedding: number[], importance: number, keywords?: string, trustScore?: number): Promise<void>;
+    updateMemoryContentWithClient(client: pg.PoolClient, 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>;
+    softDeleteMemory(userId: string, id: string): Promise<void>;
+    softDeleteMemoryWithClient(client: pg.PoolClient, userId: string, id: string): Promise<void>;
+    /** Mark memory as temporally expired (contradicted/superseded). Preserved for temporal queries. */
+    expireMemory(userId: string, id: string): Promise<void>;
+    expireMemoryWithClient(client: pg.PoolClient, userId: string, id: string): Promise<void>;
+    touchMemory(id: string): Promise<void>;
+    countMemories(userId?: string): Promise<number>;
+    countNeedsClarification(userId: string): Promise<number>;
+    updateOpinionConfidence(userId: string, memoryId: string, newConfidence: number): Promise<void>;
+    backdateMemories(ids: string[], timestamp: Date): Promise<void>;
+    storeAtomicFacts(facts: StoreAtomicFactInput[]): Promise<string[]>;
+    storeForesight(entries: StoreForesightInput[]): Promise<string[]>;
+    replaceAtomicFactsForMemory(userId: string, parentMemoryId: string, facts: StoreAtomicFactInput[]): Promise<string[]>;
+    replaceForesightForMemory(userId: string, parentMemoryId: string, 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[]>;
+    deleteBySource(userId: string, sourceSite: string): Promise<import("./repository-document-delete.js").DeleteBySourceResult>;
+    deleteAll(userId?: string): Promise<void>;
+    createLinks(links: MemoryLink[]): Promise<number>;
+    createLinksWithClient(client: pg.PoolClient, links: MemoryLink[]): Promise<number>;
+    findLinkCandidates(userId: string, embedding: number[], threshold: number, excludeId: string, limit?: number): Promise<{
+        id: string;
+        similarity: number;
+    }[]>;
+    findLinkCandidatesWithClient(client: pg.PoolClient, 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[]>;
+    fetchMemoriesByIds(userId: string, ids: string[], queryEmbedding: number[], referenceTime?: Date, includeExpired?: boolean): Promise<import("./repository-types.js").SearchResult[]>;
+    findTemporalNeighbors(userId: string, anchorTimestamps: Date[], queryEmbedding: number[], windowMinutes: number, excludeIds: Set<string>, limit: number, referenceTime?: Date): Promise<import("./repository-types.js").SearchResult[]>;
+    countLinks(): Promise<number>;
+    /**
+     * Workspace-scoped vector search with agent filtering and visibility enforcement.
+     */
+    searchSimilarInWorkspace(workspaceId: string, queryEmbedding: number[], limit: number, agentScope?: AgentScope, callerAgentId?: string, referenceTime?: Date): Promise<import("./repository-types.js").SearchResult[]>;
+    /**
+     * Find near-duplicate memories within a workspace for AUDN conflict detection.
+     */
+    findNearDuplicatesInWorkspace(workspaceId: string, embedding: number[], threshold: number, limit?: number, agentScope?: AgentScope, callerAgentId?: string): Promise<import("./repository-vector-search.js").CandidateRow[]>;
+}

package/dist/db/memory-repository.js

@@ -0,0 +1,232 @@
+/**
+ * @deprecated Phase 5 — use domain-facing store interfaces from `stores.ts` instead.
+ *
+ * This facade remains for two reasons:
+ * 1. `getPool()` is still needed by PPR and deferred-audn (raw pool access).
+ * 2. External helper modules (iterative-retrieval, agentic-retrieval, query-expansion,
+ *    etc.) still type their params as MemoryRepository. Those will be migrated
+ *    file-by-file to accept SearchStore/EntityStore.
+ *
+ * Remove this file once all consumers use stores.* and pool is exposed directly.
+ */
+import { countMemories, countNeedsClarification, findKeywordCandidates, findNearDuplicates, findNearDuplicatesInWorkspace, findTemporalNeighbors, findTopicCandidates, getEpisode, getMemory, getMemoryWithClient, getMemoryStats, listMemories, listMemoriesInWorkspace, getMemoryInWorkspace, searchHybridSimilar, searchKeywordSimilar, searchSimilar, searchSimilarInWorkspace, } from './repository-read.js';
+import { backdateMemories, deleteAll, expireMemory, expireMemoryWithClient, softDeleteMemory, softDeleteMemoryInWorkspace, softDeleteMemoryWithClient, storeCanonicalMemoryObject, storeEpisode, storeEpisodeWithClient, storeMemory, storeMemoryWithClient, touchMemory, updateMemoryContent, updateMemoryContentWithClient, updateMemoryMetadata, updateOpinionConfidence, } from './repository-write.js';
+import { deleteBySource } from './repository-document-delete.js';
+import { createLinks, countLinks, fetchMemoriesByIds, findLinkCandidates, findLinkCandidatesWithClient, findLinkedMemoryIds, } from './repository-links.js';
+import { listAtomicFactsForMemory, listForesightForMemory, replaceAtomicFactsForMemory, replaceForesightForMemory, searchAtomicFactsHybrid, storeAtomicFacts, storeForesight, } from './repository-representations.js';
+export class MemoryRepository {
+    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. When supplied, the `deleteAll`
+     * wipe path routes each blob to the adapter registered for its
+     * `storage_provider` — historical legacy rows (e.g. `local-fs://`
+     * on a Filecoin-active deployment) go to the registered legacy
+     * adapter. When absent, `repository-write.deleteAll` falls back to
+     * `singleStoreRegistry(rawContentStore)` (the pre-Phase-4a behavior)
+     * so existing test/back-compat constructions stay working.
+     */
+    storeRegistry;
+    constructor(pool, options = {}) {
+        this.pool = pool;
+        this.rawContentStore = options.rawContentStore ?? null;
+        this.storeRegistry = options.storeRegistry;
+    }
+    getPool() {
+        return this.pool;
+    }
+    async storeEpisode(input) {
+        return storeEpisode(this.pool, input);
+    }
+    async storeEpisodeWithClient(client, input) {
+        return storeEpisodeWithClient(client, input);
+    }
+    async storeCanonicalMemoryObject(input) {
+        return storeCanonicalMemoryObject(this.pool, input);
+    }
+    async getEpisode(id) {
+        return getEpisode(this.pool, id);
+    }
+    async storeMemory(input) {
+        return storeMemory(this.pool, input);
+    }
+    async storeMemoryWithClient(client, input) {
+        return storeMemoryWithClient(client, input);
+    }
+    async getMemory(id, userId) {
+        return getMemory(this.pool, id, userId, false);
+    }
+    async getMemoryIncludingDeleted(id, userId) {
+        return getMemory(this.pool, id, userId, true);
+    }
+    async getMemoryIncludingDeletedWithClient(client, id, userId) {
+        return getMemoryWithClient(client, id, userId, true);
+    }
+    async listMemories(userId, limit = 20, offset = 0, sourceSite, episodeId) {
+        return listMemories(this.pool, userId, limit, offset, sourceSite, episodeId);
+    }
+    /** Fetch the text and timestamp for all non-deleted memories for a user's
+     * conversation. memories.column is `content`, not `text` — alias to the
+     * caller's expected shape.
+     *
+     * BEAM/AMB note: AMB encodes BEAM conversation_id INTO user_id, so each
+     * ingest creates a fresh episode_id but conversation memories accumulate
+     * under the same user_id. Match on user_id only so the reflect worker sees
+     * ALL memories from the active conversation, not just the last ingest. */
+    async findByConversation(userId, conversationId) {
+        void conversationId;
+        const { rows } = await this.pool.query(`SELECT id, content, observed_at
+       FROM memories
+       WHERE user_id = $1 AND deleted_at IS NULL
+       ORDER BY observed_at ASC`, [userId]);
+        return rows.map(r => ({ id: r.id, text: r.content, observedAt: r.observed_at }));
+    }
+    async listMemoriesInWorkspace(workspaceId, limit = 20, offset = 0, callerAgentId) {
+        return listMemoriesInWorkspace(this.pool, workspaceId, limit, offset, callerAgentId);
+    }
+    async getMemoryInWorkspace(id, workspaceId, callerAgentId) {
+        return getMemoryInWorkspace(this.pool, id, workspaceId, callerAgentId);
+    }
+    async softDeleteMemoryInWorkspace(id, workspaceId) {
+        return softDeleteMemoryInWorkspace(this.pool, id, workspaceId);
+    }
+    async getMemoryStats(userId) {
+        return getMemoryStats(this.pool, userId);
+    }
+    async findMemoriesByNamespace(userId, namespace, limit = 20) {
+        const { listMemoriesByNamespace } = await import('./repository-read.js');
+        return listMemoriesByNamespace(this.pool, userId, namespace, limit);
+    }
+    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 findNearDuplicatesWithClient(client, userId, embedding, threshold, limit = 3) {
+        return findNearDuplicates(client, userId, embedding, threshold, limit);
+    }
+    async findKeywordCandidates(userId, keywords, limit = 5, includeExpired = false) {
+        return findKeywordCandidates(this.pool, userId, keywords, limit, includeExpired);
+    }
+    async findKeywordCandidatesWithClient(client, userId, keywords, limit = 5) {
+        return findKeywordCandidates(client, userId, keywords, limit);
+    }
+    async findTopicCandidates(userId, queryEmbedding, limit) {
+        return findTopicCandidates(this.pool, userId, queryEmbedding, limit);
+    }
+    async updateMemoryContent(userId, id, content, embedding, importance, keywords, trustScore) {
+        return updateMemoryContent(this.pool, userId, id, content, embedding, importance, keywords, trustScore);
+    }
+    async updateMemoryContentWithClient(client, userId, id, content, embedding, importance, keywords, trustScore) {
+        return updateMemoryContentWithClient(client, userId, id, content, embedding, importance, keywords, trustScore);
+    }
+    async updateMemoryMetadata(userId, id, metadata) {
+        return updateMemoryMetadata(this.pool, userId, id, metadata);
+    }
+    async softDeleteMemory(userId, id) {
+        return softDeleteMemory(this.pool, userId, id);
+    }
+    async softDeleteMemoryWithClient(client, userId, id) {
+        return softDeleteMemoryWithClient(client, userId, id);
+    }
+    /** Mark memory as temporally expired (contradicted/superseded). Preserved for temporal queries. */
+    async expireMemory(userId, id) {
+        return expireMemory(this.pool, userId, id);
+    }
+    async expireMemoryWithClient(client, userId, id) {
+        return expireMemoryWithClient(client, userId, id);
+    }
+    async touchMemory(id) {
+        return touchMemory(this.pool, id);
+    }
+    async countMemories(userId) {
+        return countMemories(this.pool, userId);
+    }
+    async countNeedsClarification(userId) {
+        return countNeedsClarification(this.pool, userId);
+    }
+    async updateOpinionConfidence(userId, memoryId, newConfidence) {
+        return updateOpinionConfidence(this.pool, userId, memoryId, newConfidence);
+    }
+    async backdateMemories(ids, timestamp) {
+        return backdateMemories(this.pool, ids, timestamp);
+    }
+    async storeAtomicFacts(facts) {
+        return storeAtomicFacts(this.pool, facts);
+    }
+    async storeForesight(entries) {
+        return storeForesight(this.pool, entries);
+    }
+    async replaceAtomicFactsForMemory(userId, parentMemoryId, facts) {
+        return replaceAtomicFactsForMemory(this.pool, userId, parentMemoryId, facts);
+    }
+    async replaceForesightForMemory(userId, parentMemoryId, entries) {
+        return replaceForesightForMemory(this.pool, userId, parentMemoryId, entries);
+    }
+    async listAtomicFactsForMemory(userId, parentMemoryId) {
+        return listAtomicFactsForMemory(this.pool, userId, parentMemoryId);
+    }
+    async listForesightForMemory(userId, parentMemoryId) {
+        return listForesightForMemory(this.pool, userId, parentMemoryId);
+    }
+    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 createLinks(links) {
+        return createLinks(this.pool, links);
+    }
+    async createLinksWithClient(client, links) {
+        return createLinks(client, links);
+    }
+    async findLinkCandidates(userId, embedding, threshold, excludeId, limit = 10) {
+        return findLinkCandidates(this.pool, userId, embedding, threshold, excludeId, limit);
+    }
+    async findLinkCandidatesWithClient(client, userId, embedding, threshold, excludeId, limit = 10) {
+        return findLinkCandidatesWithClient(client, userId, embedding, threshold, excludeId, limit);
+    }
+    async findLinkedMemoryIds(memoryIds, excludeIds, limit) {
+        return findLinkedMemoryIds(this.pool, memoryIds, excludeIds, limit);
+    }
+    async fetchMemoriesByIds(userId, ids, queryEmbedding, referenceTime, includeExpired = false) {
+        return fetchMemoriesByIds(this.pool, userId, ids, queryEmbedding, referenceTime, includeExpired);
+    }
+    async findTemporalNeighbors(userId, anchorTimestamps, queryEmbedding, windowMinutes, excludeIds, limit, referenceTime) {
+        return findTemporalNeighbors(this.pool, userId, anchorTimestamps, queryEmbedding, windowMinutes, excludeIds, limit, referenceTime);
+    }
+    async countLinks() {
+        return countLinks(this.pool);
+    }
+    /**
+     * Workspace-scoped vector search with agent filtering and visibility enforcement.
+     */
+    async searchSimilarInWorkspace(workspaceId, queryEmbedding, limit, agentScope = 'all', callerAgentId, referenceTime) {
+        return searchSimilarInWorkspace(this.pool, workspaceId, queryEmbedding, limit, agentScope, callerAgentId, referenceTime);
+    }
+    /**
+     * Find near-duplicate memories within a workspace for AUDN conflict detection.
+     */
+    async findNearDuplicatesInWorkspace(workspaceId, embedding, threshold, limit = 3, agentScope = 'all', callerAgentId) {
+        return findNearDuplicatesInWorkspace(this.pool, workspaceId, embedding, threshold, limit, agentScope, callerAgentId);
+    }
+}

package/dist/db/migrate.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Run schema migration against the configured database.
+ * Replaces {{EMBEDDING_DIMENSIONS}} in schema.sql with the configured value.
+ * Usage: pnpm migrate (uses .env) or pnpm migrate:test (uses .env.test)
+ */
+export {};

package/dist/db/migrate.js

@@ -0,0 +1,36 @@
+/**
+ * Run schema migration against the configured database.
+ * Replaces {{EMBEDDING_DIMENSIONS}} in schema.sql with the configured value.
+ * Usage: pnpm migrate (uses .env) or pnpm migrate:test (uses .env.test)
+ */
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { pool } from './pool.js';
+import { config } from '../config.js';
+import { resolveEmbeddingDimensions } from '../services/embedding.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function stripVectorIndexes(sql) {
+    if (!config.skipVectorIndexes)
+        return sql;
+    // Matches both CREATE INDEX and CREATE INDEX IF NOT EXISTS forms — schema.sql
+    // uses the idempotent form so it can re-run on every startup without data loss.
+    return sql.replace(/CREATE INDEX (IF NOT EXISTS )?idx_[a-z_]+_embedding ON [a-z_]+\n  USING hnsw \(embedding vector_cosine_ops\)\n  WITH \(m = 16, ef_construction = 200\);(\n\n|\n?$)/g, '');
+}
+async function migrate() {
+    const envDims = process.env.EMBEDDING_DIMENSIONS ? parseInt(process.env.EMBEDDING_DIMENSIONS, 10) : null;
+    const embeddingDimensions = envDims ?? await resolveEmbeddingDimensions();
+    console.log(`[migrate] Resolved dimensions: ${embeddingDimensions} (from env: ${envDims})`);
+    const schemaPath = resolve(__dirname, 'schema.sql');
+    const rawSql = readFileSync(schemaPath, 'utf-8');
+    const dimensionedSql = rawSql.replace(/\{\{EMBEDDING_DIMENSIONS\}\}/g, String(embeddingDimensions));
+    const sql = stripVectorIndexes(dimensionedSql);
+    console.log(`Running migration (embedding dimensions: ${embeddingDimensions}, vector indexes: ${config.skipVectorIndexes ? 'off' : 'on'})...`);
+    await pool.query(sql);
+    console.log('Migration complete.');
+    await pool.end();
+}
+migrate().catch((err) => {
+    console.error('Migration failed:', err);
+    process.exit(1);
+});

package/dist/db/mmr.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Maximal Marginal Relevance (MMR) reranking.
+ *
+ * Greedily selects results that balance relevance to the query against
+ * redundancy with already-selected results. This improves diversity in
+ * the top-K, which is critical for multi-hop queries that need different
+ * types of facts to compose a complete answer.
+ *
+ * score_mmr(d) = lambda * score(d) - (1 - lambda) * max(sim(d, selected_i))
+ *
+ * Source: Carbonell & Goldstein (1998), Phase 2 roadmap item.
+ */
+import type { SearchResult } from './repository-types.js';
+export declare function applyMMR(candidates: SearchResult[], queryEmbedding: number[], limit: number, lambda: number): SearchResult[];

package/dist/db/mmr.js

@@ -0,0 +1,57 @@
+/**
+ * Maximal Marginal Relevance (MMR) reranking.
+ *
+ * Greedily selects results that balance relevance to the query against
+ * redundancy with already-selected results. This improves diversity in
+ * the top-K, which is critical for multi-hop queries that need different
+ * types of facts to compose a complete answer.
+ *
+ * score_mmr(d) = lambda * score(d) - (1 - lambda) * max(sim(d, selected_i))
+ *
+ * Source: Carbonell & Goldstein (1998), Phase 2 roadmap item.
+ */
+import { cosineSimilarity } from '../vector-math.js';
+export function applyMMR(candidates, queryEmbedding, limit, lambda) {
+    if (candidates.length <= 1)
+        return candidates.slice(0, limit);
+    const selected = [];
+    const remaining = new Set(candidates.map((_, i) => i));
+    const bestIndex = selectHighestScore(candidates);
+    selected.push(candidates[bestIndex]);
+    remaining.delete(bestIndex);
+    while (selected.length < limit && remaining.size > 0) {
+        const bestCandidate = selectBestMmrCandidate(candidates, selected, remaining, lambda);
+        if (bestCandidate === -1)
+            break;
+        selected.push(candidates[bestCandidate]);
+        remaining.delete(bestCandidate);
+    }
+    return selected;
+}
+/** Find the index of the candidate with the highest relevance score. */
+function selectHighestScore(candidates) {
+    return candidates.reduce((best, current, i) => (current.score > candidates[best].score ? i : best), 0);
+}
+/** Select the remaining candidate with the best MMR score, or -1 if none. */
+function selectBestMmrCandidate(candidates, selected, remaining, lambda) {
+    let bestMmrScore = -Infinity;
+    let bestCandidate = -1;
+    for (const candidateIndex of remaining) {
+        const mmrScore = computeMmrScore(candidates[candidateIndex], selected, lambda);
+        if (mmrScore > bestMmrScore) {
+            bestMmrScore = mmrScore;
+            bestCandidate = candidateIndex;
+        }
+    }
+    return bestCandidate;
+}
+/** Compute MMR score: balance relevance against redundancy with selected set. */
+function computeMmrScore(candidate, selected, lambda) {
+    let maxRedundancy = 0;
+    for (const selectedResult of selected) {
+        const redundancy = cosineSimilarity(candidate.embedding, selectedResult.embedding);
+        if (redundancy > maxRedundancy)
+            maxRedundancy = redundancy;
+    }
+    return lambda * candidate.score - (1 - lambda) * maxRedundancy;
+}