@massa-ai/core 1.2.1

package/dist/services/graph/graph-store-pg.js

@@ -0,0 +1,422 @@
+/**
+ * Graph Store — PostgreSQL implementation.
+ *
+ * CRUD operations for memory edges in the knowledge graph using Prisma ORM.
+ * Natively async.
+ *
+ * Implements the backend-agnostic `IGraphStore` contract (structural gap #14).
+ * Method names are normalized to match the PostgreSQL store so `getGraphStore()`
+ * can return an `IGraphStore` without backend-specific dispatch.
+ */
+import { getPrismaClient } from "../query/prisma-client.js";
+import { logger, } from "@massa-ai/shared";
+import { Prisma } from "../../generated/prisma/index.js";
+function metadataForEdge(edge) {
+    return {
+        autoExtracted: edge.autoExtracted ?? false,
+        ...(edge.evidence !== undefined ? { evidence: edge.evidence } : {}),
+    };
+}
+function rowToEdge(row) {
+    const metadata = row.metadata && typeof row.metadata === "object"
+        ? row.metadata
+        : {};
+    const storedEvidence = metadata.evidence;
+    return {
+        id: row.id.toString(),
+        sourceId: row.from_id,
+        targetId: row.to_id,
+        relationType: row.edge_type,
+        weight: row.weight,
+        evidence: typeof storedEvidence === "string"
+            ? storedEvidence
+            : row.metadata
+                ? JSON.stringify(row.metadata)
+                : undefined,
+        autoExtracted: metadata.autoExtracted === true,
+        createdAt: row.created_at,
+    };
+}
+/**
+ * Lazily-initialized Prisma client proxy.
+ *
+ * The original `const prisma = getPrismaClient()` ran at module-eval, which
+ * forced every importer of this module (transitively, of graph-store-factory)
+ * to construct a Prisma client — and that throws in environments where the
+ * PG/Bun-PostgreSQL prisma adapter isn't installed (e.g. PostgreSQL-only test/dev).
+ * The Proxy defers construction to first actual use, so merely importing the
+ * module is side-effect-free.
+ */
+const prisma = new Proxy({}, {
+    get(_target, prop) {
+        const client = getPrismaClient();
+        const value = Reflect.get(client, prop);
+        return typeof value === "function" ? value.bind(client) : value;
+    },
+});
+export class GraphStorePg {
+    static instance = null;
+    static getInstance() {
+        if (!GraphStorePg.instance) {
+            GraphStorePg.instance = new GraphStorePg();
+        }
+        return GraphStorePg.instance;
+    }
+    constructor() {
+        logger.info("GraphStorePg initialized (PostgreSQL)");
+    }
+    // ── CRUD ──────────────────────────────────────────────────────
+    /**
+     * Create a new edge between two memories.
+     * Automatically updates weight if edge already exists.
+     *
+     * Accepts the canonical `EdgeCreateInput` (single object) so it satisfies
+     * `IGraphStore.createEdge` exactly like the PostgreSQL store.
+     */
+    async createEdge(edge) {
+        if (edge.sourceId === edge.targetId) {
+            logger.warn("Cannot create self-referencing edge", { sourceId: edge.sourceId });
+            return null;
+        }
+        const weight = edge.weight ?? 1.0;
+        const metadata = JSON.stringify(metadataForEdge(edge));
+        try {
+            const rows = await prisma.$queryRaw `
+        INSERT INTO memory_edges
+          (from_id, to_id, edge_type, weight, metadata, created_at, updated_at)
+        VALUES
+          (${edge.sourceId}, ${edge.targetId}, ${edge.relationType}, ${weight}, ${metadata}::jsonb, NOW(), NOW())
+        ON CONFLICT (from_id, to_id, edge_type) DO UPDATE SET
+          weight = GREATEST(memory_edges.weight, EXCLUDED.weight),
+          metadata = CASE
+            WHEN EXCLUDED.metadata ? 'evidence'
+            THEN jsonb_set(
+              COALESCE(memory_edges.metadata, '{}'::jsonb),
+              '{evidence}',
+              EXCLUDED.metadata->'evidence',
+              true
+            )
+            ELSE memory_edges.metadata
+          END,
+          updated_at = NOW()
+        RETURNING id, from_id, to_id, edge_type, weight, metadata, created_at
+      `;
+            return rows[0] ? rowToEdge(rows[0]) : null;
+        }
+        catch (error) {
+            logger.error("Failed to create edge", error);
+            return null;
+        }
+    }
+    /**
+     * Get edge by (sourceId, targetId, relationType) triple.
+     * IGraphStore-conformant alias; the PG schema stores edges by from/to/type.
+     */
+    async getEdge(sourceId, targetId, relationType) {
+        const rows = await prisma.$queryRaw `
+      SELECT id, from_id, to_id, edge_type, weight, metadata, created_at
+      FROM memory_edges
+      WHERE from_id = ${sourceId}
+        AND to_id = ${targetId}
+        AND edge_type = ${relationType}
+      LIMIT 1
+    `;
+        return rows[0] ? rowToEdge(rows[0]) : null;
+    }
+    /**
+     * Find edges matching filters.
+     * Kept as a non-contract helper (contract callers use getAllEdges).
+     */
+    async findEdges(filter) {
+        const where = {};
+        if (filter.sourceId) {
+            where.fromId = filter.sourceId;
+        }
+        if (filter.targetId) {
+            where.toId = filter.targetId;
+        }
+        if (filter.relationTypes && filter.relationTypes.length > 0) {
+            where.edgeType = { in: filter.relationTypes };
+        }
+        if (filter.minWeight !== undefined) {
+            where.weight = { gte: filter.minWeight };
+        }
+        const edges = await prisma.memoryEdge.findMany({
+            where,
+            orderBy: { weight: 'desc' },
+            take: filter.limit || 100,
+        });
+        return edges.map(edge => ({
+            id: edge.id.toString(),
+            sourceId: edge.fromId,
+            targetId: edge.toId,
+            relationType: edge.edgeType,
+            weight: edge.weight,
+            evidence: edge.metadata ? JSON.stringify(edge.metadata) : undefined,
+            autoExtracted: false,
+            createdAt: edge.createdAt,
+        }));
+    }
+    /**
+     * Get all edges from a source memory.
+     * Not on the contract; used internally by bfsNeighbors.
+     */
+    async getOutgoingEdges(sourceId, limit = 100) {
+        return this.findEdges({ sourceId, limit });
+    }
+    /**
+     * Get all edges to a target memory.
+     */
+    async getIncomingEdges(targetId, limit = 100) {
+        return this.findEdges({ targetId, limit });
+    }
+    /**
+     * Phase 7c: async BFS over outgoing edges (mirror of GraphStore.bfsNeighbors).
+     */
+    async bfsNeighbors(seedIds, depth) {
+        const d = Math.max(1, Math.floor(depth));
+        const visited = new Set(seedIds);
+        const out = new Set();
+        let frontier = seedIds.filter((id) => id != null && id !== "");
+        for (let hop = 0; hop < d && frontier.length > 0; hop++) {
+            const next = [];
+            for (const id of frontier) {
+                try {
+                    const edges = await this.getOutgoingEdges(id);
+                    for (const e of edges) {
+                        const t = e.targetId;
+                        if (!visited.has(t)) {
+                            visited.add(t);
+                            out.add(t);
+                            next.push(t);
+                        }
+                    }
+                }
+                catch {
+                    // Defensive: a single broken seed never aborts the whole BFS.
+                }
+            }
+            frontier = next;
+        }
+        return [...out];
+    }
+    /**
+     * Get all edges connected to a memory (both incoming and outgoing).
+     * IGraphStore-conformant; replaces the legacy `getConnectedEdges` name.
+     */
+    async getAllEdges(memoryId, filter) {
+        const conditions = [
+            Prisma.sql `(from_id = ${memoryId} OR to_id = ${memoryId})`,
+        ];
+        if (filter?.relationTypes?.length) {
+            conditions.push(Prisma.sql `edge_type = ANY(${filter.relationTypes}::text[])`);
+        }
+        if (filter?.minWeight !== undefined) {
+            conditions.push(Prisma.sql `weight >= ${filter.minWeight}`);
+        }
+        if (filter?.autoExtractedOnly) {
+            conditions.push(Prisma.sql `COALESCE((metadata->>'autoExtracted')::boolean, false) = true`);
+        }
+        const limit = filter?.limit ?? 50;
+        const rows = await prisma.$queryRaw(Prisma.sql `
+      SELECT id, from_id, to_id, edge_type, weight, metadata, created_at
+      FROM memory_edges
+      WHERE ${Prisma.join(conditions, " AND ")}
+      ORDER BY weight DESC, created_at DESC
+      LIMIT ${limit}
+    `);
+        return rows.map(rowToEdge);
+    }
+    /**
+     * Update edge weight (set). IGraphStore-conformant alias for updateEdgeWeight.
+     */
+    async updateWeight(id, weight) {
+        return this.updateEdgeWeight(id, weight);
+    }
+    /**
+     * Legacy alias kept for callers that used the PG-specific name.
+     */
+    async updateEdgeWeight(id, weight) {
+        const numericId = Number.parseInt(id, 10);
+        if (!Number.isSafeInteger(numericId))
+            return false;
+        const clamped = Math.max(0, Math.min(1, weight));
+        const changed = await prisma.$executeRaw `
+      UPDATE memory_edges SET weight = ${clamped}, updated_at = NOW()
+      WHERE id = ${numericId}
+    `;
+        return changed > 0;
+    }
+    /**
+     * Atomically increment edge weight by delta, capped at maxWeight.
+     * IGraphStore-conformant; the single UPDATE prevents lost increments when
+     * multiple reinforcement calls race.
+     */
+    async incrementEdgeWeight(sourceId, targetId, relationType, delta, maxWeight = 1.0) {
+        const changed = await prisma.$executeRaw `
+      UPDATE memory_edges
+      SET weight = LEAST(weight + ${delta}, ${maxWeight}), updated_at = NOW()
+      WHERE from_id = ${sourceId}
+        AND to_id = ${targetId}
+        AND edge_type = ${relationType}
+    `;
+        return changed > 0;
+    }
+    /**
+     * Delete an edge by ID.
+     */
+    async deleteEdge(id) {
+        try {
+            await prisma.memoryEdge.delete({
+                where: { id: parseInt(id) },
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Delete all edges connected to a memory.
+     * IGraphStore-conformant alias; replaces the legacy `deleteEdgesByMemory` name.
+     */
+    async deleteEdgesForMemory(memoryId) {
+        const result = await prisma.memoryEdge.deleteMany({
+            where: {
+                OR: [
+                    { fromId: memoryId },
+                    { toId: memoryId },
+                ],
+            },
+        });
+        return result.count;
+    }
+    /**
+     * Legacy alias kept for callers that used the PG-specific name.
+     */
+    async deleteEdgesByMemory(memoryId) {
+        return this.deleteEdgesForMemory(memoryId);
+    }
+    /**
+     * Batch create edges.
+     */
+    async batchCreateEdges(edges) {
+        const results = await Promise.all(edges.map(edge => this.createEdge(edge)));
+        return results.filter((edge) => edge !== null).length;
+    }
+    // ── Analytics ──────────────────────────────────────────────────
+    /**
+     * Degree centrality for a memory (in + out + total).
+     * IGraphStore-conformant.
+     */
+    async getDegree(memoryId) {
+        const outCount = await prisma.memoryEdge.count({ where: { fromId: memoryId } });
+        const inCount = await prisma.memoryEdge.count({ where: { toId: memoryId } });
+        return { in: inCount, out: outCount, total: inCount + outCount };
+    }
+    /**
+     * Find memories with the most connections (hub nodes).
+     * IGraphStore-conformant. Uses raw grouping since Prisma has no direct
+     * UNION+GROUP BY helper; falls back to client-side aggregation over a
+     * bounded scan.
+     */
+    async getHubMemories(limit = 10) {
+        const edges = await prisma.memoryEdge.findMany({
+            select: { fromId: true, toId: true },
+            take: 5000,
+        });
+        const counts = new Map();
+        for (const e of edges) {
+            counts.set(e.fromId, (counts.get(e.fromId) ?? 0) + 1);
+            counts.set(e.toId, (counts.get(e.toId) ?? 0) + 1);
+        }
+        return [...counts.entries()]
+            .map(([memoryId, degree]) => ({ memoryId, degree }))
+            .sort((a, b) => b.degree - a.degree)
+            .slice(0, limit);
+    }
+    /**
+     * Get statistics about the graph.
+     * IGraphStore-conformant alias for getGraphStats, normalizing the return
+     * shape to match the PostgreSQL store (byRelation/autoExtracted/avgWeight).
+     */
+    async getStats() {
+        const totals = await prisma.$queryRaw `
+      SELECT
+        COUNT(*) AS total,
+        COUNT(*) FILTER (
+          WHERE COALESCE((metadata->>'autoExtracted')::boolean, false) = true
+        ) AS auto_extracted,
+        AVG(weight) AS avg_weight
+      FROM memory_edges
+    `;
+        const relationRows = await prisma.$queryRaw `
+      SELECT edge_type, COUNT(*) AS count
+      FROM memory_edges
+      GROUP BY edge_type
+    `;
+        const byRelation = {};
+        for (const row of relationRows)
+            byRelation[row.edge_type] = Number(row.count);
+        const total = totals[0];
+        return {
+            totalEdges: Number(total?.total ?? 0),
+            byRelation,
+            autoExtracted: Number(total?.auto_extracted ?? 0),
+            avgWeight: Math.round((total?.avg_weight ?? 0) * 100) / 100,
+        };
+    }
+    /**
+     * Find paths between two memories (BFS, up to maxDepth)
+     */
+    async findPaths(fromId, toId, maxDepth = 3) {
+        // For PostgreSQL, we can use recursive CTE
+        const result = await prisma.$queryRaw `
+      WITH RECURSIVE paths AS (
+        -- Base case: direct edges
+        SELECT
+          from_id,
+          to_id,
+          ARRAY[from_id, to_id]::text[] as path,
+          weight as total_weight,
+          1 as depth
+        FROM memory_edges
+        WHERE from_id = ${fromId}
+
+        UNION
+
+        -- Recursive case: extend paths
+        SELECT
+          p.from_id,
+          e.to_id,
+          p.path || e.to_id,
+          p.total_weight * e.weight,
+          p.depth + 1
+        FROM paths p
+        JOIN memory_edges e ON p.to_id = e.from_id
+        WHERE e.to_id != ALL(p.path)  -- Avoid cycles
+          AND p.depth < ${maxDepth}
+      )
+      SELECT
+        array_to_string(path, ',') as path,
+        total_weight
+      FROM paths
+      WHERE to_id = ${toId}
+      ORDER BY total_weight DESC
+      LIMIT 10
+    `;
+        return result.map(row => ({
+            path: row.path.split(','),
+            weight: row.total_weight,
+        }));
+    }
+    /**
+     * Clear all edges (for testing)
+     */
+    async clear() {
+        await prisma.memoryEdge.deleteMany();
+        logger.info("GraphStore cleared");
+    }
+}
+export const graphStorePg = GraphStorePg.getInstance();
+//# sourceMappingURL=graph-store-pg.js.map

package/dist/services/graph/graph-store-pg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-store-pg.js","sourceRoot":"","sources":["../../../src/services/graph/graph-store-pg.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAGL,MAAM,GACP,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAC;AAczD,SAAS,eAAe,CAAC,IAAqB;IAC5C,OAAO;QACL,aAAa,EAAE,IAAI,CAAC,aAAa,IAAI,KAAK;QAC1C,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpE,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,GAAkB;IACnC,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ;QAC/D,CAAC,CAAC,GAAG,CAAC,QAAmC;QACzC,CAAC,CAAC,EAAE,CAAC;IACP,MAAM,cAAc,GAAG,QAAQ,CAAC,QAAQ,CAAC;IAEzC,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC,QAAQ,EAAE;QACrB,QAAQ,EAAE,GAAG,CAAC,OAAO;QACrB,QAAQ,EAAE,GAAG,CAAC,KAAK;QACnB,YAAY,EAAE,GAAG,CAAC,SAA+B;QACjD,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,QAAQ,EAAE,OAAO,cAAc,KAAK,QAAQ;YAC1C,CAAC,CAAC,cAAc;YAChB,CAAC,CAAC,GAAG,CAAC,QAAQ;gBACZ,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC;gBAC9B,CAAC,CAAC,SAAS;QACf,aAAa,EAAE,QAAQ,CAAC,aAAa,KAAK,IAAI;QAC9C,SAAS,EAAE,GAAG,CAAC,UAAU;KAC1B,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,GAAiB,IAAI,KAAK,CACpC,EAAkB,EAClB;IACE,GAAG,CAAC,OAAO,EAAE,IAAI;QACf,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QACxC,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAClE,CAAC;CACF,CACF,CAAC;AAEF,MAAM,OAAO,YAAY;IACf,MAAM,CAAC,QAAQ,GAAwB,IAAI,CAAC;IAEpD,MAAM,CAAC,WAAW;QAChB,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC;YAC3B,YAAY,CAAC,QAAQ,GAAG,IAAI,YAAY,EAAE,CAAC;QAC7C,CAAC;QACD,OAAO,YAAY,CAAC,QAAQ,CAAC;IAC/B,CAAC;IAED;QACE,MAAM,CAAC,IAAI,CAAC,uCAAuC,CAAC,CAAC;IACvD,CAAC;IAED,iEAAiE;IAEjE;;;;;;OAMG;IACH,KAAK,CAAC,UAAU,CAAC,IAAqB;QACpC,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC;YACpC,MAAM,CAAC,IAAI,CAAC,qCAAqC,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;YAChF,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC;QAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;QACvD,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,SAAS,CAAiB;;;;aAI7C,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,YAAY,KAAK,MAAM,KAAK,QAAQ;;;;;;;;;;;;;;;OAenF,CAAC;YAEF,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC7C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,uBAAuB,EAAE,KAAc,CAAC,CAAC;YACtD,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,OAAO,CACX,QAAgB,EAChB,QAAgB,EAChB,YAAgC;QAEhC,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,SAAS,CAAiB;;;wBAGhC,QAAQ;sBACV,QAAQ;0BACJ,YAAY;;KAEjC,CAAC;QAEF,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7C,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,SAAS,CAAC,MAAkB;QAChC,MAAM,KAAK,GAAQ,EAAE,CAAC;QAEtB,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACpB,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC;QACjC,CAAC;QAED,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACpB,KAAK,CAAC,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC;QAC/B,CAAC;QAED,IAAI,MAAM,CAAC,aAAa,IAAI,MAAM,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5D,KAAK,CAAC,QAAQ,GAAG,EAAE,EAAE,EAAE,MAAM,CAAC,aAAa,EAAE,CAAC;QAChD,CAAC;QAED,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YACnC,KAAK,CAAC,MAAM,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;QAC3C,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC;YAC7C,KAAK;YACL,OAAO,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE;YAC3B,IAAI,EAAE,MAAM,CAAC,KAAK,IAAI,GAAG;SAC1B,CAAC,CAAC;QAEH,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACxB,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE;YACtB,QAAQ,EAAE,IAAI,CAAC,MAAM;YACrB,QAAQ,EAAE,IAAI,CAAC,IAAI;YACnB,YAAY,EAAE,IAAI,CAAC,QAA8B;YACjD,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS;YACnE,aAAa,EAAE,KAAK;YACpB,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,CAAC,CAAC,CAAC;IACN,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,gBAAgB,CAAC,QAAgB,EAAE,QAAgB,GAAG;QAC1D,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,gBAAgB,CAAC,QAAgB,EAAE,QAAgB,GAAG;QAC1D,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,YAAY,CAAC,OAAiB,EAAE,KAAa;QACjD,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;QACzC,MAAM,OAAO,GAAG,IAAI,GAAG,CAAS,OAAO,CAAC,CAAC;QACzC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;QAC9B,IAAI,QAAQ,GAAa,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,IAAI,IAAI,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAEzE,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,CAAC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC;YACxD,MAAM,IAAI,GAAa,EAAE,CAAC;YAC1B,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;gBAC1B,IAAI,CAAC;oBACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC;oBAC9C,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;wBACtB,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;wBACrB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;4BACpB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;4BACf,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;4BACX,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;wBACf,CAAC;oBACH,CAAC;gBACH,CAAC;gBAAC,MAAM,CAAC;oBACP,8DAA8D;gBAChE,CAAC;YACH,CAAC;YACD,QAAQ,GAAG,IAAI,CAAC;QAClB,CAAC;QACD,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC;IAClB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,WAAW,CAAC,QAAgB,EAAE,MAAmB;QACrD,MAAM,UAAU,GAAiB;YAC/B,MAAM,CAAC,GAAG,CAAA,cAAc,QAAQ,eAAe,QAAQ,GAAG;SAC3D,CAAC;QACF,IAAI,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC;YAClC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAA,mBAAmB,MAAM,CAAC,aAAa,WAAW,CAAC,CAAC;QAChF,CAAC;QACD,IAAI,MAAM,EAAE,SAAS,KAAK,SAAS,EAAE,CAAC;YACpC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAA,aAAa,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;QAC7D,CAAC;QACD,IAAI,MAAM,EAAE,iBAAiB,EAAE,CAAC;YAC9B,UAAU,CAAC,IAAI,CACb,MAAM,CAAC,GAAG,CAAA,+DAA+D,CAC1E,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,EAAE,KAAK,IAAI,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,SAAS,CAAkB,MAAM,CAAC,GAAG,CAAA;;;cAGrD,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC;;cAEhC,KAAK;KACd,CAAC,CAAC;QAEH,OAAO,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,YAAY,CAAC,EAAU,EAAE,MAAc;QAC3C,OAAO,IAAI,CAAC,gBAAgB,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IAC3C,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,gBAAgB,CAAC,EAAU,EAAE,MAAc;QAC/C,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QAC1C,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC;YAAE,OAAO,KAAK,CAAC;QACnD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QACjD,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,WAAW,CAAA;yCACH,OAAO;mBAC7B,SAAS;KACvB,CAAC;QACF,OAAO,OAAO,GAAG,CAAC,CAAC;IACrB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,mBAAmB,CACvB,QAAgB,EAChB,QAAgB,EAChB,YAAgC,EAChC,KAAa,EACb,SAAS,GAAG,GAAG;QAEf,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,WAAW,CAAA;;oCAER,KAAK,KAAK,SAAS;wBAC/B,QAAQ;sBACV,QAAQ;0BACJ,YAAY;KACjC,CAAC;QACF,OAAO,OAAO,GAAG,CAAC,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,UAAU,CAAC,EAAU;QACzB,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC;gBAC7B,KAAK,EAAE,EAAE,EAAE,EAAE,QAAQ,CAAC,EAAE,CAAC,EAAE;aAC5B,CAAC,CAAC;YACH,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,oBAAoB,CAAC,QAAgB;QACzC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC;YAChD,KAAK,EAAE;gBACL,EAAE,EAAE;oBACF,EAAE,MAAM,EAAE,QAAQ,EAAE;oBACpB,EAAE,IAAI,EAAE,QAAQ,EAAE;iBACnB;aACF;SACF,CAAC,CAAC;QAEH,OAAO,MAAM,CAAC,KAAK,CAAC;IACtB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,mBAAmB,CAAC,QAAgB;QACxC,OAAO,IAAI,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAC7C,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,gBAAgB,CAAC,KAAwB;QAC7C,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC/B,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CACzC,CAAC;QACF,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,MAAM,CAAC;IACxD,CAAC;IAED,kEAAkE;IAElE;;;OAGG;IACH,KAAK,CAAC,SAAS,CAAC,QAAgB;QAC9B,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;QAChF,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;QAC7E,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,GAAG,QAAQ,EAAE,CAAC;IACnE,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,cAAc,CAAC,QAAgB,EAAE;QACrC,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC;YAC7C,MAAM,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE;YACpC,IAAI,EAAE,IAAI;SACX,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;QACzC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACtD,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACpD,CAAC;QACD,OAAO,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;aACzB,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;aACnD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;aACnC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACrB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,QAAQ;QAMZ,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,SAAS,CAIlC;;;;;;;;KAQF,CAAC;QACF,MAAM,YAAY,GAAG,MAAM,MAAM,CAAC,SAAS,CAGxC;;;;KAIF,CAAC;QACF,MAAM,UAAU,GAA2B,EAAE,CAAC;QAC9C,KAAK,MAAM,GAAG,IAAI,YAAY;YAAE,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC9E,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QAExB,OAAO;YACL,UAAU,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,IAAI,CAAC,CAAC;YACrC,UAAU;YACV,aAAa,EAAE,MAAM,CAAC,KAAK,EAAE,cAAc,IAAI,CAAC,CAAC;YACjD,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,UAAU,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG;SAC5D,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,SAAS,CACb,MAAc,EACd,IAAY,EACZ,WAAmB,CAAC;QAEpB,2CAA2C;QAC3C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,SAAS,CAA+C;;;;;;;;;;0BAU9D,MAAM;;;;;;;;;;;;;;0BAcN,QAAQ;;;;;;sBAMZ,IAAI;;;KAGrB,CAAC;QAEF,OAAO,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACxB,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC;YACzB,MAAM,EAAE,GAAG,CAAC,YAAY;SACzB,CAAC,CAAC,CAAC;IACN,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACT,MAAM,MAAM,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC;QACrC,MAAM,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IACpC,CAAC;;AAGH,MAAM,CAAC,MAAM,YAAY,GAAG,YAAY,CAAC,WAAW,EAAE,CAAC"}

package/dist/services/graph/index.d.ts

@@ -0,0 +1,7 @@
+export { GraphStorePg } from './graph-store-pg.js';
+export { RelationExtractor } from './relation-extractor.js';
+export { GraphQueries } from './graph-queries.js';
+export { MemoryGraphService } from './memory-graph.service.js';
+export { getGraphStore, resetGraphStore } from './graph-store-factory.js';
+export type { MemoryRow, MemoryRowWithEmbedding, RelatedMemory, EdgeCreateInput, EdgeFilter, IGraphStore, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/services/graph/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/graph/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC1E,YAAY,EACV,SAAS,EACT,sBAAsB,EACtB,aAAa,EACb,eAAe,EACf,UAAU,EACV,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/services/graph/index.js

@@ -0,0 +1,6 @@
+export { GraphStorePg } from './graph-store-pg.js';
+export { RelationExtractor } from './relation-extractor.js';
+export { GraphQueries } from './graph-queries.js';
+export { MemoryGraphService } from './memory-graph.service.js';
+export { getGraphStore, resetGraphStore } from './graph-store-factory.js';
+//# sourceMappingURL=index.js.map

package/dist/services/graph/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/services/graph/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/services/graph/memory-graph.service.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Memory Graph Service
+ *
+ * Orchestration layer that coordinates graph operations triggered
+ * by memory lifecycle events (store, search, delete).
+ *
+ * This service owns the composition of GraphStore, RelationExtractor,
+ * and GraphQueries. Tools and other services interact with the graph
+ * exclusively through this service, keeping them decoupled from
+ * graph internals.
+ *
+ * Uses `getGraphStore()` (the factory) so the active backend is selected
+ * by `DATABASE_URL` — PostgreSQL or PostgreSQL — rather than hardcoding the
+ * PostgreSQL singleton (structural gap #14).
+ */
+import { MemoryRelationType, MemoryEdge, GraphQueryOptions, ContradictionPair } from "@massa-ai/shared";
+import type { RelatedMemory, MemoryRow } from "./types.js";
+export type { GraphQueryOptions, ContradictionPair, RelatedMemory, MemoryRow };
+export declare class MemoryGraphService {
+    private static instance;
+    private readonly store;
+    private readonly extractor;
+    private readonly queries;
+    private constructor();
+    static getInstance(): MemoryGraphService;
+    /**
+     * Called after a memory is successfully stored.
+     * Creates explicit links and triggers background relation extraction.
+     */
+    onMemoryStored(memoryId: string, linkTo?: string[]): Promise<void>;
+    /**
+     * Called when a memory is deleted.
+     * Cleans up all connected edges.
+     */
+    onMemoryDeleted(memoryId: string): Promise<void>;
+    /**
+     * Get memories related to a given memory via graph traversal.
+     */
+    getRelatedContext(memoryId: string, options?: GraphQueryOptions): Promise<RelatedMemory[]>;
+    /**
+     * Find the shortest path between two memories.
+     */
+    findPath(fromId: string, toId: string, maxDepth?: number): Promise<import("@massa-ai/shared").GraphPath | null>;
+    /**
+     * Detect contradictions in the memory graph.
+     */
+    findContradictions(limit?: number): Promise<ContradictionPair[]>;
+    /**
+     * Follow the decision chain leading to a memory.
+     */
+    getDecisionChain(memoryId: string, maxDepth?: number): Promise<RelatedMemory[]>;
+    /**
+     * Get hub memories (most connected nodes).
+     */
+    getHubMemories(limit?: number): Promise<{
+        memory: MemoryRow;
+        degree: number;
+    }[]>;
+    /**
+     * Get a human-readable summary of a memory's neighborhood.
+     * Useful for injecting into LLM context alongside search results.
+     */
+    getNeighborhoodSummary(memoryId: string): Promise<string>;
+    /**
+     * Create a manual edge between two memories.
+     */
+    linkMemories(sourceId: string, targetId: string, relationType: MemoryRelationType, options?: {
+        weight?: number;
+        evidence?: string;
+    }): Promise<MemoryEdge | null>;
+    /**
+     * Remove an edge by ID.
+     */
+    unlinkMemories(edgeId: string): Promise<boolean>;
+    /**
+     * Get all edges for a memory.
+     */
+    getEdges(memoryId: string): Promise<MemoryEdge[]>;
+    /**
+     * Get graph-level statistics.
+     */
+    getStats(): Promise<{
+        totalEdges: number;
+        byRelation: Record<string, number>;
+        autoExtracted: number;
+        avgWeight: number;
+    }>;
+    /**
+     * Get degree centrality for a specific memory.
+     */
+    getDegree(memoryId: string): Promise<{
+        in: number;
+        out: number;
+        total: number;
+    }>;
+}
+//# sourceMappingURL=memory-graph.service.d.ts.map

package/dist/services/graph/memory-graph.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-graph.service.d.ts","sourceRoot":"","sources":["../../../src/services/graph/memory-graph.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,kBAAkB,EAClB,UAAU,EACV,iBAAiB,EACjB,iBAAiB,EAElB,MAAM,kBAAkB,CAAC;AAI1B,OAAO,KAAK,EAAe,aAAa,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGxE,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,aAAa,EAAE,SAAS,EAAE,CAAC;AAE/E,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAmC;IAE1D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IAEvC,OAAO;IAQP,MAAM,CAAC,WAAW,IAAI,kBAAkB;IASxC;;;OAGG;IACG,cAAc,CAClB,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,MAAM,EAAO,GACpB,OAAO,CAAC,IAAI,CAAC;IAgChB;;;OAGG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBtD;;OAEG;IACG,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB;IAIrE;;OAEG;IACG,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM;IAI9D;;OAEG;IACG,kBAAkB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAItE;;OAEG;IACG,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM;IAI1D;;OAEG;IACG,cAAc,CAAC,KAAK,CAAC,EAAE,MAAM;;;;IAInC;;;OAGG;IACG,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAM/D;;OAEG;IACG,YAAY,CAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,kBAAkB,EAChC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAC/C,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAU7B;;OAEG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAItD;;OAEG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM;IAM/B;;OAEG;IACG,QAAQ;;;;;;IAId;;OAEG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM;;;;;CAGjC"}