memo-grafter 0.2.7 → 0.3.0

package/dist/store/postgres-pgvector/GraphStore.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import postgres, {} from "postgres";
+import { memoGrafterExtensionNames, memoGrafterIndexNames, memoGrafterTableNames } from "../../schema/index.js";
 import { cosineSimilarity } from "../../utils/drift/cosineSimilarity.js";
 import { normalizeTags } from "../../utils/tags.js";
 import { parseVector, toVectorLiteral } from "../../utils/vector/vectorLiteral.js";
@@ -10,9 +11,33 @@ export class PostgresGraphStore {
             max: 10,
             idle_timeout: 30,
             connect_timeout: 10,
+            onnotice: () => undefined,
         });
     }
     async initialize() {
+        await this.verifySchema();
+    }
+    async verifySchema() {
+        const [extensions, tables] = await Promise.all([
+            this.getExistingExtensions(memoGrafterExtensionNames),
+            this.getExistingTables(memoGrafterTableNames),
+        ]);
+        const missingExtensions = memoGrafterExtensionNames.filter((name) => !extensions.has(name));
+        const missingTables = memoGrafterTableNames.filter((name) => !tables.has(name));
+        if (missingExtensions.length === 0 && missingTables.length === 0) {
+            return;
+        }
+        const missing = [
+            ...missingExtensions.map((name) => `extension ${name}`),
+            ...missingTables.map((name) => `table ${name}`),
+        ].join(", ");
+        throw new Error(`MemoGrafter database schema is not initialized. Missing ${missing}. `
+            + "Run: npx memo-grafter migrate --db <connection-string>");
+    }
+    async migrate() {
+        const existingExtensions = await this.getExistingExtensions(memoGrafterExtensionNames);
+        const existingTables = await this.getExistingTables(memoGrafterTableNames);
+        const existingIndexes = await this.getExistingIndexes(memoGrafterIndexNames);
         await this.sql `CREATE EXTENSION IF NOT EXISTS vector`;
         await this.sql `CREATE EXTENSION IF NOT EXISTS pgcrypto`;
         await this.sql `
@@ -52,6 +77,8 @@ export class PostgresGraphStore {
         agent_color   TEXT,
         fleet_id      TEXT,
         agent_id      TEXT,
+        suppressed    BOOLEAN NOT NULL DEFAULT FALSE,
+        suppressed_at TIMESTAMPTZ,
         created_at    TIMESTAMPTZ DEFAULT NOW(),
         UNIQUE (segment_id)
       )
@@ -85,6 +112,8 @@ export class PostgresGraphStore {
         source_title  TEXT,
         superseded_by UUID REFERENCES mg_memory_nodes(id),
         decayed       BOOLEAN NOT NULL DEFAULT FALSE,
+        forgotten     BOOLEAN NOT NULL DEFAULT FALSE,
+        forgotten_at  TIMESTAMPTZ,
         has_conflict  BOOLEAN NOT NULL DEFAULT FALSE,
         agent_color   TEXT,
         fleet_id      TEXT,
@@ -102,6 +131,22 @@ export class PostgresGraphStore {
         await this.sql `
       ALTER TABLE mg_memory_nodes
       ADD COLUMN IF NOT EXISTS has_conflict BOOLEAN NOT NULL DEFAULT FALSE
+    `;
+        await this.sql `
+      ALTER TABLE mg_memory_nodes
+      ADD COLUMN IF NOT EXISTS forgotten BOOLEAN NOT NULL DEFAULT FALSE
+    `;
+        await this.sql `
+      ALTER TABLE mg_memory_nodes
+      ADD COLUMN IF NOT EXISTS forgotten_at TIMESTAMPTZ
+    `;
+        await this.sql `
+      ALTER TABLE mg_topic_nodes
+      ADD COLUMN IF NOT EXISTS suppressed BOOLEAN NOT NULL DEFAULT FALSE
+    `;
+        await this.sql `
+      ALTER TABLE mg_topic_nodes
+      ADD COLUMN IF NOT EXISTS suppressed_at TIMESTAMPTZ
     `;
         await this.sql `
       ALTER TABLE mg_topic_nodes
@@ -157,6 +202,20 @@ export class PostgresGraphStore {
     `;
         await this.migrateExistingNodeTable();
         await this.createIndexes();
+        return {
+            extensions: memoGrafterExtensionNames.map((name) => ({
+                name,
+                status: existingExtensions.has(name) ? "exists" : "created",
+            })),
+            tables: memoGrafterTableNames.map((name) => ({
+                name,
+                status: existingTables.has(name) ? "exists" : "created",
+            })),
+            indexes: memoGrafterIndexNames.map((name) => ({
+                name,
+                status: existingIndexes.has(name) ? "exists" : "created",
+            })),
+        };
     }
     async saveMessages(sessionId, messages) {
         await this.saveMessagesAt(sessionId, 0, messages);
@@ -308,6 +367,7 @@ export class PostgresGraphStore {
       JOIN mg_topic_nodes n ON n.id = e.src_id
       WHERE n.session_id = ${sessionId}
         AND e.type = ${type}
+        AND n.suppressed = FALSE
     `;
         return rows.map((row) => ({
             srcId: row.src_id,
@@ -397,6 +457,7 @@ export class PostgresGraphStore {
       SELECT COUNT(*)::int AS count
       FROM mg_topic_nodes
       WHERE session_id = ${sessionId}
+        AND suppressed = FALSE
     `;
         return rows[0]?.count ?? 0;
     }
@@ -406,6 +467,7 @@ export class PostgresGraphStore {
         const rows = await this.sql `
       SELECT * FROM mg_topic_nodes
       WHERE ${searchTaggedSessions ? this.sql `TRUE` : this.sql `session_id = ${sessionId}`}
+        ${options.includeSuppressed ? this.sql `` : this.sql `AND suppressed = FALSE`}
         ${this.topicTagsFilterSql(tags, options.tagMode)}
       ORDER BY session_id ASC, topic_order ASC, created_at ASC
     `;
@@ -415,6 +477,7 @@ export class PostgresGraphStore {
         const rows = await this.sql `
       SELECT * FROM mg_topic_nodes
       WHERE session_id = ${sessionId}
+        AND suppressed = FALSE
       ORDER BY topic_order DESC, created_at DESC
       LIMIT 1
     `;
@@ -468,11 +531,15 @@ export class PostgresGraphStore {
     }
     async getMemoriesByTopic(topicNodeId) {
         const rows = await this.sql `
-      SELECT * FROM mg_memory_nodes
-      WHERE topic_node_id = ${topicNodeId}
-        AND decayed = false
-        AND superseded_by IS NULL
-      ORDER BY created_at ASC
+      SELECT memory.*
+      FROM mg_memory_nodes memory
+      JOIN mg_topic_nodes topic ON topic.id = memory.topic_node_id
+      WHERE memory.topic_node_id = ${topicNodeId}
+        AND memory.decayed = false
+        AND memory.superseded_by IS NULL
+        AND memory.forgotten = false
+        AND topic.suppressed = false
+      ORDER BY memory.created_at ASC
     `;
         return rows.map((row) => this.rowToMemoryNode(row));
     }
@@ -496,13 +563,136 @@ export class PostgresGraphStore {
     `;
         return rows.map((row) => this.rowToMemoryEdge(row));
     }
+    async getMemoryHistoryById(memoryNodeId, options = {}) {
+        const anchor = await this.getMemoryNodeById(memoryNodeId, options.sessionId);
+        if (!anchor) {
+            return {
+                anchorMemoryId: memoryNodeId,
+                ...(options.sessionId ? { sessionId: options.sessionId } : {}),
+                entries: [],
+                edges: [],
+                currentMemory: null,
+            };
+        }
+        const memories = await this.getMemoryNodesByFactKey(anchor.subject, anchor.predicate, {
+            sessionId: options.sessionId ?? anchor.sessionId,
+        });
+        const byId = new Map(memories.map((memory) => [memory.id, memory]));
+        byId.set(anchor.id, anchor);
+        const firstPassEdges = await this.getMemoryEdgesForMemoryIds([...byId.keys()]);
+        for (const id of this.getConnectedMemoryIds(firstPassEdges)) {
+            if (!byId.has(id)) {
+                byId.set(id, null);
+            }
+        }
+        const missingIds = [...byId.entries()]
+            .filter(([, memory]) => memory == null)
+            .map(([id]) => id);
+        for (const memory of await this.getMemoryNodesByIds(missingIds, options.sessionId ?? anchor.sessionId)) {
+            byId.set(memory.id, memory);
+        }
+        const historyMemories = [...byId.values()].filter((memory) => memory != null);
+        const edges = await this.getMemoryEdgesForMemoryIds(historyMemories.map((memory) => memory.id));
+        return this.buildMemoryHistoryResult(historyMemories, edges, {
+            anchorMemoryId: memoryNodeId,
+            subject: anchor.subject,
+            predicate: anchor.predicate,
+            sessionId: options.sessionId ?? anchor.sessionId,
+        });
+    }
+    async getMemoryHistoryByFact(subject, predicate, options = {}) {
+        const memories = await this.getMemoryNodesByFactKey(subject, predicate, options);
+        const edges = await this.getMemoryEdgesForMemoryIds(memories.map((memory) => memory.id));
+        return this.buildMemoryHistoryResult(memories, edges, {
+            subject,
+            predicate,
+            ...(options.sessionId ? { sessionId: options.sessionId } : {}),
+        });
+    }
+    async getMemoryDiff(fromMemoryId, toMemoryId) {
+        const [from, to] = await Promise.all([
+            this.getMemoryNodeById(fromMemoryId),
+            this.getMemoryNodeById(toMemoryId),
+        ]);
+        if (!from) {
+            throw new Error(`Memory ${fromMemoryId} was not found.`);
+        }
+        if (!to) {
+            throw new Error(`Memory ${toMemoryId} was not found.`);
+        }
+        const edges = (await this.getMemoryEdgesForMemoryIds([from.id, to.id]))
+            .filter((edge) => (edge.sourceId === from.id && edge.targetId === to.id)
+            || (edge.sourceId === to.id && edge.targetId === from.id));
+        const updateEdges = edges.filter((edge) => edge.edgeType === "updates");
+        const conflictEdges = edges.filter((edge) => edge.edgeType === "conflicts");
+        const fields = this.diffMemoryFields(from, to);
+        return {
+            from,
+            to,
+            fields,
+            changedFields: fields.filter((field) => field.changed),
+            relationship: {
+                supersedes: to.supersededBy === from.id || updateEdges.some((edge) => edge.sourceId === from.id && edge.targetId === to.id),
+                supersededBy: from.supersededBy === to.id || updateEdges.some((edge) => edge.sourceId === to.id && edge.targetId === from.id),
+                conflicts: conflictEdges.length > 0,
+                updateEdges,
+                conflictEdges,
+            },
+        };
+    }
     async listMemoryNodesForMaintenance() {
         const rows = await this.sql `
-      SELECT * FROM mg_memory_nodes
-      ORDER BY session_id ASC, created_at ASC, id ASC
+      SELECT memory.*
+      FROM mg_memory_nodes memory
+      JOIN mg_topic_nodes topic ON topic.id = memory.topic_node_id
+      WHERE memory.forgotten = FALSE
+        AND topic.suppressed = FALSE
+      ORDER BY memory.session_id ASC, memory.created_at ASC, memory.id ASC
     `;
         return rows.map((row) => this.rowToMemoryNode(row));
     }
+    async forgetMemory(memoryNodeId) {
+        const changed = await this.forgetMemories([memoryNodeId]);
+        return changed > 0;
+    }
+    async forgetMemories(memoryNodeIds) {
+        if (memoryNodeIds.length === 0)
+            return 0;
+        const rows = await this.sql `
+      UPDATE mg_memory_nodes
+      SET
+        forgotten = TRUE,
+        forgotten_at = COALESCE(forgotten_at, NOW())
+      WHERE id = ANY(${this.sql.array(memoryNodeIds)}::uuid[])
+        AND forgotten = FALSE
+      RETURNING id
+    `;
+        return rows.length;
+    }
+    async suppressTopic(topicNodeId) {
+        const rows = await this.sql `
+      UPDATE mg_topic_nodes
+      SET
+        suppressed = TRUE,
+        suppressed_at = COALESCE(suppressed_at, NOW())
+      WHERE id = ${topicNodeId}
+        AND suppressed = FALSE
+      RETURNING id
+    `;
+        return rows.length > 0;
+    }
+    async restoreTopic(topicNodeId) {
+        const rows = await this.sql `
+      UPDATE mg_topic_nodes
+      SET
+        suppressed = FALSE,
+        suppressed_at = NULL
+      WHERE id = ${topicNodeId}
+        AND suppressed = TRUE
+      RETURNING id
+    `;
+        return rows.length > 0;
+    }
     async markMemoryNodesConflicting(memoryNodeIds) {
         if (memoryNodeIds.length === 0)
             return 0;
@@ -572,16 +762,45 @@ export class PostgresGraphStore {
         return true;
     }
     async searchMemories(embedding, sessionId, limit, minSimilarity, options = {}) {
+        if (options.sessionIds && options.sessionIds.length > 0) {
+            return this.searchMemoriesAcrossSessions(embedding, options.sessionIds, limit, minSimilarity, options);
+        }
         const tags = normalizeTags(options.tags);
         const searchTaggedSessions = options.scope === "tagged" && tags.length > 0;
         const rows = await this.sql `
-      SELECT *, 1 - (embedding <=> ${toVectorLiteral(embedding)}::vector) AS similarity
-      FROM mg_memory_nodes
-      WHERE ${searchTaggedSessions ? this.sql `TRUE` : this.sql `session_id = ${sessionId}`}
-        AND decayed = false
-        AND superseded_by IS NULL
-        ${this.memoryTagsFilterSql(tags, options.tagMode)}
-        AND 1 - (embedding <=> ${toVectorLiteral(embedding)}::vector) >= ${minSimilarity}
+      SELECT memory.*, 1 - (memory.embedding <=> ${toVectorLiteral(embedding)}::vector) AS similarity
+      FROM mg_memory_nodes memory
+      JOIN mg_topic_nodes topic ON topic.id = memory.topic_node_id
+      WHERE ${searchTaggedSessions ? this.sql `TRUE` : this.sql `memory.session_id = ${sessionId}`}
+        AND memory.decayed = false
+        AND memory.superseded_by IS NULL
+        AND memory.forgotten = false
+        AND topic.suppressed = false
+        ${this.memoryTagsFilterSql(tags, options.tagMode, "memory")}
+        AND 1 - (memory.embedding <=> ${toVectorLiteral(embedding)}::vector) >= ${minSimilarity}
+      ORDER BY similarity DESC
+      LIMIT ${limit}
+    `;
+        return rows.map((row) => ({
+            ...this.rowToMemoryNode(row),
+            similarity: row.similarity,
+        }));
+    }
+    async searchMemoriesAcrossSessions(embedding, sessionIds, limit, minSimilarity, options = {}) {
+        if (sessionIds.length === 0)
+            return [];
+        const tags = normalizeTags(options.tags);
+        const rows = await this.sql `
+      SELECT memory.*, 1 - (memory.embedding <=> ${toVectorLiteral(embedding)}::vector) AS similarity
+      FROM mg_memory_nodes memory
+      JOIN mg_topic_nodes topic ON topic.id = memory.topic_node_id
+      WHERE memory.session_id = ANY(${this.sql.array(sessionIds)})
+        AND memory.decayed = false
+        AND memory.superseded_by IS NULL
+        AND memory.forgotten = false
+        AND topic.suppressed = false
+        ${this.memoryTagsFilterSql(tags, options.tagMode, "memory")}
+        AND 1 - (memory.embedding <=> ${toVectorLiteral(embedding)}::vector) >= ${minSimilarity}
       ORDER BY similarity DESC
       LIMIT ${limit}
     `;
@@ -634,6 +853,22 @@ export class PostgresGraphStore {
       SELECT *, 1 - (embedding <=> ${toVectorLiteral(embedding)}::vector) AS similarity
       FROM mg_topic_nodes
       WHERE session_id = ${sessionId}
+        AND suppressed = FALSE
+        ${options.excludeNodeId ? this.sql `AND id != ${options.excludeNodeId}` : this.sql ``}
+        ${options.minSimilarity === undefined ? this.sql `` : this.sql `AND 1 - (embedding <=> ${toVectorLiteral(embedding)}::vector) >= ${options.minSimilarity}`}
+      ORDER BY embedding <=> ${toVectorLiteral(embedding)}::vector ASC
+      LIMIT ${options.k ?? 5}
+    `;
+        return rows.map((row) => this.rowToNode(row));
+    }
+    async getSimilarNodesAcrossSessions(embedding, sessionIds, options = {}) {
+        if (sessionIds.length === 0)
+            return [];
+        const rows = await this.sql `
+      SELECT *, 1 - (embedding <=> ${toVectorLiteral(embedding)}::vector) AS similarity
+      FROM mg_topic_nodes
+      WHERE session_id = ANY(${this.sql.array(sessionIds)})
+        AND suppressed = FALSE
         ${options.excludeNodeId ? this.sql `AND id != ${options.excludeNodeId}` : this.sql ``}
         ${options.minSimilarity === undefined ? this.sql `` : this.sql `AND 1 - (embedding <=> ${toVectorLiteral(embedding)}::vector) >= ${options.minSimilarity}`}
       ORDER BY embedding <=> ${toVectorLiteral(embedding)}::vector ASC
@@ -646,6 +881,7 @@ export class PostgresGraphStore {
       SELECT *, 1 - (embedding <=> ${toVectorLiteral(embedding)}::vector) AS similarity
       FROM mg_topic_nodes
       WHERE fleet_id = ${fleetId}
+        AND suppressed = FALSE
         ${options.agentColor ? this.sql `AND agent_color = ${options.agentColor}` : this.sql ``}
         ${options.excludeNodeId ? this.sql `AND id != ${options.excludeNodeId}` : this.sql ``}
         ${options.minSimilarity === undefined ? this.sql `` : this.sql `AND 1 - (embedding <=> ${toVectorLiteral(embedding)}::vector) >= ${options.minSimilarity}`}
@@ -659,6 +895,7 @@ export class PostgresGraphStore {
       SELECT * FROM mg_topic_nodes
       WHERE fleet_id = ${fleetId}
         AND agent_color = ${agentColor}
+        AND suppressed = FALSE
       ORDER BY topic_order ASC, created_at ASC
     `;
         return rows.map((row) => this.rowToNode(row));
@@ -703,6 +940,14 @@ export class PostgresGraphStore {
         agent_id = ${metadata.agentId},
         agent_color = ${metadata.agentColor}
       WHERE session_id = ${sessionId}
+    `;
+        await this.sql `
+      UPDATE mg_memory_nodes
+      SET
+        fleet_id = ${metadata.fleetId},
+        agent_id = ${metadata.agentId},
+        agent_color = ${metadata.agentColor}
+      WHERE session_id = ${sessionId}
     `;
     }
     async setSessionTags(sessionId, tags) {
@@ -724,6 +969,7 @@ export class PostgresGraphStore {
       FROM mg_topic_nodes
       WHERE session_id = ${sessionId}
         AND topic_order = ${topicOrder - 1}
+        AND suppressed = FALSE
       LIMIT 1
     `;
         return rows[0] ? this.rowToNode(rows[0]) : null;
@@ -767,6 +1013,7 @@ export class PostgresGraphStore {
       SELECT * FROM mg_topic_nodes
       WHERE id = ANY(${this.sql.array(ids)})
         ${sessionId ? this.sql `AND session_id = ${sessionId}` : this.sql ``}
+        AND suppressed = FALSE
       ORDER BY topic_order ASC, created_at ASC
     `;
         return rows.map((row) => this.rowToNode(row));
@@ -825,7 +1072,10 @@ export class PostgresGraphStore {
         const copiedNodes = [];
         const nextMessageIndex = await this.getNextMessageIndex(targetSessionId);
         const nextTopicOrder = await this.getNextTopicOrder(targetSessionId);
-        for (const [index, node] of nodes.entries()) {
+        for (const node of nodes) {
+            if (node.suppressed)
+                continue;
+            const index = copiedNodes.length;
             const messageIndex = nextMessageIndex + index;
             await this.saveMessagesAt(targetSessionId, messageIndex, [{
                     role: "assistant",
@@ -919,8 +1169,182 @@ export class PostgresGraphStore {
         AND session_id = ${sourceNode.sessionId}
         AND decayed = FALSE
         AND superseded_by IS NULL
+        AND forgotten = FALSE
     `;
     }
+    async getMemoryNodeById(memoryNodeId, sessionId) {
+        if (sessionId) {
+            const rows = await this.sql `
+        SELECT *
+        FROM mg_memory_nodes
+        WHERE id = ${memoryNodeId}::uuid
+          AND session_id = ${sessionId}
+        LIMIT 1
+      `;
+            return rows[0] ? this.rowToMemoryNode(rows[0]) : null;
+        }
+        const rows = await this.sql `
+      SELECT *
+      FROM mg_memory_nodes
+      WHERE id = ${memoryNodeId}::uuid
+      LIMIT 1
+    `;
+        return rows[0] ? this.rowToMemoryNode(rows[0]) : null;
+    }
+    async getMemoryNodesByIds(memoryNodeIds, sessionId) {
+        if (memoryNodeIds.length === 0)
+            return [];
+        if (sessionId) {
+            const rows = await this.sql `
+        SELECT *
+        FROM mg_memory_nodes
+        WHERE id = ANY(${this.sql.array(memoryNodeIds)}::uuid[])
+          AND session_id = ${sessionId}
+        ORDER BY created_at ASC, id ASC
+      `;
+            return rows.map((row) => this.rowToMemoryNode(row));
+        }
+        const rows = await this.sql `
+      SELECT *
+      FROM mg_memory_nodes
+      WHERE id = ANY(${this.sql.array(memoryNodeIds)}::uuid[])
+      ORDER BY created_at ASC, id ASC
+    `;
+        return rows.map((row) => this.rowToMemoryNode(row));
+    }
+    async getMemoryNodesByFactKey(subject, predicate, options = {}) {
+        const normalizedSubject = this.normalizeMemoryHistoryPart(subject);
+        const normalizedPredicate = this.normalizeMemoryHistoryPart(predicate);
+        if (options.sessionId) {
+            const rows = await this.sql `
+        SELECT *
+        FROM mg_memory_nodes
+        WHERE lower(regexp_replace(trim(subject), '[[:space:]]+', ' ', 'g')) = ${normalizedSubject}
+          AND lower(regexp_replace(trim(predicate), '[[:space:]]+', ' ', 'g')) = ${normalizedPredicate}
+          AND session_id = ${options.sessionId}
+        ORDER BY created_at ASC, id ASC
+      `;
+            return rows.map((row) => this.rowToMemoryNode(row));
+        }
+        const rows = await this.sql `
+      SELECT *
+      FROM mg_memory_nodes
+      WHERE lower(regexp_replace(trim(subject), '[[:space:]]+', ' ', 'g')) = ${normalizedSubject}
+        AND lower(regexp_replace(trim(predicate), '[[:space:]]+', ' ', 'g')) = ${normalizedPredicate}
+      ORDER BY created_at ASC, id ASC
+    `;
+        return rows.map((row) => this.rowToMemoryNode(row));
+    }
+    async getMemoryEdgesForMemoryIds(memoryNodeIds) {
+        if (memoryNodeIds.length === 0)
+            return [];
+        const rows = await this.sql `
+      SELECT DISTINCT *
+      FROM mg_memory_edges
+      WHERE source_id = ANY(${this.sql.array(memoryNodeIds)}::uuid[])
+         OR target_id = ANY(${this.sql.array(memoryNodeIds)}::uuid[])
+      ORDER BY created_at ASC, id ASC
+    `;
+        return rows.map((row) => this.rowToMemoryEdge(row));
+    }
+    buildMemoryHistoryResult(memories, edges, metadata) {
+        const memoriesById = new Map(memories.map((memory) => [memory.id, memory]));
+        const visibleEdges = edges.filter((edge) => memoriesById.has(edge.sourceId) && memoriesById.has(edge.targetId));
+        const sortedMemories = [...memories].sort((left, right) => left.createdAt.getTime() - right.createdAt.getTime()
+            || left.id.localeCompare(right.id));
+        const entries = sortedMemories.map((memory, index) => {
+            const updateEdges = visibleEdges.filter((edge) => edge.edgeType === "updates"
+                && (edge.sourceId === memory.id || edge.targetId === memory.id));
+            const conflictEdges = visibleEdges.filter((edge) => edge.edgeType === "conflicts"
+                && (edge.sourceId === memory.id || edge.targetId === memory.id));
+            const supersedes = [
+                ...sortedMemories
+                    .filter((candidate) => candidate.supersededBy === memory.id)
+                    .map((candidate) => candidate.id),
+                ...updateEdges
+                    .filter((edge) => edge.sourceId === memory.id)
+                    .map((edge) => edge.targetId),
+            ];
+            const conflictsWith = conflictEdges.map((edge) => edge.sourceId === memory.id ? edge.targetId : edge.sourceId);
+            return {
+                memory,
+                versionIndex: index,
+                status: this.resolveMemoryHistoryStatus(memory, conflictEdges),
+                supersedes: [...new Set(supersedes)],
+                supersededBy: memory.supersededBy,
+                conflictsWith: [...new Set(conflictsWith)],
+                updateEdges,
+                conflictEdges,
+                createdAt: memory.createdAt,
+            };
+        });
+        return {
+            ...metadata,
+            entries,
+            edges: visibleEdges,
+            currentMemory: this.resolveCurrentMemory(sortedMemories),
+        };
+    }
+    resolveMemoryHistoryStatus(memory, conflictEdges) {
+        if (memory.forgotten)
+            return "forgotten";
+        if (memory.decayed)
+            return "decayed";
+        if (memory.supersededBy != null)
+            return "superseded";
+        if (memory.hasConflict || conflictEdges.length > 0)
+            return "conflicting";
+        return "active";
+    }
+    resolveCurrentMemory(memories) {
+        return [...memories]
+            .filter((memory) => !memory.forgotten && !memory.decayed && memory.supersededBy == null)
+            .sort((left, right) => right.createdAt.getTime() - left.createdAt.getTime()
+            || right.id.localeCompare(left.id))[0] ?? null;
+    }
+    getConnectedMemoryIds(edges) {
+        return [...new Set(edges.flatMap((edge) => [edge.sourceId, edge.targetId]))];
+    }
+    diffMemoryFields(from, to) {
+        const fields = [
+            "sessionId",
+            "topicNodeId",
+            "agentId",
+            "memoryType",
+            "sourceType",
+            "subject",
+            "predicate",
+            "value",
+            "confidence",
+            "tags",
+            "source",
+            "sourceUrl",
+            "sourceTitle",
+            "supersededBy",
+            "decayed",
+            "forgotten",
+            "forgottenAt",
+            "hasConflict",
+            "agentColor",
+            "fleetId",
+            "createdAt",
+        ];
+        return fields.map((field) => ({
+            field,
+            from: from[field],
+            to: to[field],
+            changed: !this.memoryDiffValuesEqual(from[field], to[field]),
+        }));
+    }
+    memoryDiffValuesEqual(left, right) {
+        if (left instanceof Date && right instanceof Date) {
+            return left.getTime() === right.getTime();
+        }
+        return JSON.stringify(left ?? null) === JSON.stringify(right ?? null);
+    }
+    normalizeMemoryHistoryPart(value) {
+        return value.trim().toLowerCase().replace(/\s+/g, " ");
+    }
     async deleteEdgesByNodeIds(nodeIds) {
         if (nodeIds.length === 0)
             return;
@@ -974,6 +1398,38 @@ export class PostgresGraphStore {
     async close() {
         await this.sql.end();
     }
+    async getExistingExtensions(extensionNames) {
+        if (extensionNames.length === 0)
+            return new Set();
+        const rows = await this.sql `
+      SELECT extname
+      FROM pg_extension
+    `;
+        const expected = new Set(extensionNames);
+        return new Set(rows.map((row) => row.extname).filter((name) => expected.has(name)));
+    }
+    async getExistingTables(tableNames) {
+        if (tableNames.length === 0)
+            return new Set();
+        const rows = await this.sql `
+      SELECT table_name
+      FROM information_schema.tables
+      WHERE table_schema = 'public'
+    `;
+        const expected = new Set(tableNames);
+        return new Set(rows.map((row) => row.table_name).filter((name) => expected.has(name)));
+    }
+    async getExistingIndexes(indexNames) {
+        if (indexNames.length === 0)
+            return new Set();
+        const rows = await this.sql `
+      SELECT indexname
+      FROM pg_indexes
+      WHERE schemaname = 'public'
+    `;
+        const expected = new Set(indexNames);
+        return new Set(rows.map((row) => row.indexname).filter((name) => expected.has(name)));
+    }
     async migrateExistingNodeTable() {
         await this.sql `ALTER TABLE mg_segments DROP COLUMN IF EXISTS node_id`;
         await this.sql `ALTER TABLE mg_topic_nodes ADD COLUMN IF NOT EXISTS segment_id TEXT`;
@@ -1016,6 +1472,11 @@ export class PostgresGraphStore {
         await this.sql `
       CREATE INDEX IF NOT EXISTS mg_nodes_session_idx
       ON mg_topic_nodes(session_id, topic_order)
+    `;
+        await this.sql `
+      CREATE INDEX IF NOT EXISTS idx_topic_nodes_active_lifecycle
+      ON mg_topic_nodes(session_id, suppressed)
+      WHERE suppressed = FALSE
     `;
         await this.sql `
       CREATE INDEX IF NOT EXISTS mg_topic_nodes_tags_idx
@@ -1058,6 +1519,11 @@ export class PostgresGraphStore {
         await this.sql `
       CREATE INDEX IF NOT EXISTS idx_memory_nodes_session
       ON mg_memory_nodes(session_id)
+    `;
+        await this.sql `
+      CREATE INDEX IF NOT EXISTS idx_memory_nodes_active_lifecycle
+      ON mg_memory_nodes(session_id, forgotten, decayed)
+      WHERE forgotten = FALSE
     `;
         await this.sql `
       CREATE INDEX IF NOT EXISTS idx_memory_nodes_tags
@@ -1096,9 +1562,14 @@ export class PostgresGraphStore {
             ? this.sql `AND tags && ${this.sql.array(tags)}::text[]`
             : this.sql `AND tags @> ${this.sql.array(tags)}::text[]`;
     }
-    memoryTagsFilterSql(tags, tagMode = "all") {
+    memoryTagsFilterSql(tags, tagMode = "all", tableAlias) {
         if (tags.length === 0)
             return this.sql ``;
+        if (tableAlias === "memory") {
+            return tagMode === "any"
+                ? this.sql `AND memory.tags && ${this.sql.array(tags)}::text[]`
+                : this.sql `AND memory.tags @> ${this.sql.array(tags)}::text[]`;
+        }
         return tagMode === "any"
             ? this.sql `AND tags && ${this.sql.array(tags)}::text[]`
             : this.sql `AND tags @> ${this.sql.array(tags)}::text[]`;
@@ -1142,6 +1613,8 @@ export class PostgresGraphStore {
             agentColor: row.agent_color,
             fleetId: row.fleet_id,
             agentId: row.agent_id,
+            suppressed: row.suppressed ?? false,
+            suppressedAt: row.suppressed_at,
             createdAt: row.created_at,
         };
     }
@@ -1165,6 +1638,8 @@ export class PostgresGraphStore {
             sourceTitle: row.source_title,
             supersededBy: row.superseded_by,
             decayed: row.decayed,
+            forgotten: row.forgotten ?? false,
+            forgottenAt: row.forgotten_at,
             hasConflict: row.has_conflict ?? false,
             agentColor: row.agent_color,
             fleetId: row.fleet_id,