@massa-ai/core 1.2.1

package/dist/services/graph/graph-queries.js

@@ -0,0 +1,336 @@
+/**
+ * Graph Queries
+ *
+ * Traversal and query operations over the memory knowledge graph.
+ * Provides BFS-based traversal with depth limits, path finding,
+ * contradiction detection, and hub analysis.
+ *
+ * ─────────────────────────────────────────────────────────────────
+ * PERFORMANCE OPTIMIZATIONS (Issue #4)
+ * ─────────────────────────────────────────────────────────────────
+ *
+ * ✅ Batch Loading Elimination of N+1 Queries:
+ *
+ * All traversal methods now use `loadMemoriesByIds()` to batch load
+ * memories instead of individual `loadMemory()` calls. This reduces
+ * query count from O(N) to O(1) per BFS level or operation.
+ *
+ * Before:
+ *   - getRelatedContext(): O(N) queries for N neighbors
+ *   - findContradictions(): 2×limit queries (one per memory in each pair)
+ *   - getHubMemories(): limit queries (one per hub)
+ *   - reconstructPath(): O(path_length) queries
+ *
+ * After:
+ *   - getRelatedContext(): O(maxDepth) queries (one per BFS level)
+ *   - findContradictions(): 1 query (batch load all unique memories)
+ *   - getHubMemories(): 1 query (batch load all hubs)
+ *   - reconstructPath(): 1 query (batch load entire path)
+ *
+ * Example: BFS with depth=3 and 6 neighbors per level:
+ *   - Old: 2 + 12 + 72 = 86 queries
+ *   - New: 3 queries (one per level)
+ *   - Speedup: ~29x reduction in query count
+ *
+ * Measured Performance (see graph-queries.test.ts):
+ *   - Query count reduced by 2-30x depending on graph structure
+ *   - Latency improved proportionally to query reduction
+ *   - Zero behavioral changes - all existing tests pass
+ *
+ * Implementation:
+ *   - loadMemoriesByIds(ids: string[]): Map<string, MemoryRow>
+ *   - Uses SQL WHERE id IN (...) with placeholders
+ *   - Returns Map for O(1) lookup after batch load
+ */
+import { getPrismaClient } from "../query/prisma-client.js";
+import { MemoryRelationType, } from "@massa-ai/shared";
+import { getGraphStore } from "./graph-store-factory.js";
+const DEFAULT_OPTIONS = {
+    maxDepth: 2,
+    relationTypes: [],
+    minWeight: 0.3,
+    limit: 20,
+    includeEvidence: true,
+};
+export class GraphQueries {
+    graphStore;
+    constructor(graphStore) {
+        this.graphStore = graphStore ?? getGraphStore();
+    }
+    // ── Traversal ──────────────────────────────────────────────
+    /**
+     * Get related memories using BFS traversal up to maxDepth.
+     * Returns memories ordered by (depth ASC, edge weight DESC).
+     *
+     * Performance: Batch loads all memories per BFS level, reducing
+     * query count from O(N) to O(maxDepth).
+     */
+    async getRelatedContext(memoryId, options) {
+        const opts = { ...DEFAULT_OPTIONS, ...options };
+        const visited = new Set([memoryId]);
+        const result = [];
+        // BFS queue: [memoryId, depth]
+        const queue = [[memoryId, 0]];
+        while (queue.length > 0 && result.length < opts.limit) {
+            // Process all nodes at current depth level
+            const currentLevelSize = queue.length;
+            const neighborData = [];
+            // Collect all neighbor IDs for batch loading
+            for (let i = 0; i < currentLevelSize && result.length < opts.limit; i++) {
+                const [currentId, depth] = queue.shift();
+                if (depth >= opts.maxDepth)
+                    continue;
+                // Get edges from current node
+                const edges = await this.graphStore.getAllEdges(currentId, {
+                    relationTypes: opts.relationTypes.length > 0 ? opts.relationTypes : undefined,
+                    minWeight: opts.minWeight,
+                    limit: 20,
+                });
+                for (const edge of edges) {
+                    // Determine the neighbor (other end of the edge)
+                    const neighborId = edge.sourceId === currentId ? edge.targetId : edge.sourceId;
+                    if (visited.has(neighborId))
+                        continue;
+                    visited.add(neighborId);
+                    neighborData.push({
+                        neighborId,
+                        edge,
+                        depth: depth + 1,
+                    });
+                    // Enqueue for deeper traversal
+                    if (depth + 1 < opts.maxDepth) {
+                        queue.push([neighborId, depth + 1]);
+                    }
+                }
+            }
+            // Batch load all neighbors for this level
+            if (neighborData.length > 0) {
+                const neighborIds = neighborData.map((n) => n.neighborId);
+                const memoryMap = await this.loadMemoriesByIds(neighborIds);
+                for (const { neighborId, edge, depth } of neighborData) {
+                    const memory = memoryMap.get(neighborId);
+                    if (!memory)
+                        continue;
+                    result.push({
+                        memory,
+                        edge: opts.includeEvidence
+                            ? edge
+                            : { ...edge, evidence: undefined },
+                        depth,
+                    });
+                    if (result.length >= opts.limit)
+                        break;
+                }
+            }
+        }
+        // Sort: closer depth first, higher weight first within same depth
+        result.sort((a, b) => {
+            if (a.depth !== b.depth)
+                return a.depth - b.depth;
+            return b.edge.weight - a.edge.weight;
+        });
+        return result;
+    }
+    // ── Path Finding ───────────────────────────────────────────
+    /**
+     * Find shortest path between two memories using BFS.
+     * Returns null if no path exists within maxDepth.
+     */
+    async findPath(fromId, toId, maxDepth = 5) {
+        if (fromId === toId) {
+            const memory = await this.loadMemory(fromId);
+            return memory
+                ? { nodes: [memory], edges: [], length: 0, totalWeight: 0 }
+                : null;
+        }
+        // BFS with parent tracking
+        const visited = new Map();
+        visited.set(fromId, { parentId: null, edge: null });
+        const queue = [[fromId, 0]];
+        while (queue.length > 0) {
+            const [currentId, depth] = queue.shift();
+            if (depth >= maxDepth)
+                continue;
+            const edges = await this.graphStore.getAllEdges(currentId, { limit: 30 });
+            for (const edge of edges) {
+                const neighborId = edge.sourceId === currentId ? edge.targetId : edge.sourceId;
+                if (visited.has(neighborId))
+                    continue;
+                visited.set(neighborId, { parentId: currentId, edge });
+                if (neighborId === toId) {
+                    // Reconstruct path
+                    return this.reconstructPath(fromId, toId, visited);
+                }
+                queue.push([neighborId, depth + 1]);
+            }
+        }
+        return null; // No path found
+    }
+    async reconstructPath(fromId, toId, visited) {
+        const nodeIds = [];
+        const edges = [];
+        let current = toId;
+        while (current !== fromId) {
+            nodeIds.unshift(current);
+            const info = visited.get(current);
+            if (!info || !info.parentId)
+                return null;
+            if (info.edge)
+                edges.unshift(info.edge);
+            current = info.parentId;
+        }
+        nodeIds.unshift(fromId);
+        // Batch load all path memories (eliminates N+1 query)
+        const memoryMap = await this.loadMemoriesByIds(nodeIds);
+        const nodes = nodeIds
+            .map((id) => memoryMap.get(id))
+            .filter(Boolean);
+        if (nodes.length !== nodeIds.length) {
+            // Some memories couldn't be loaded
+            return null;
+        }
+        const totalWeight = edges.reduce((sum, e) => sum + e.weight, 0);
+        return {
+            nodes,
+            edges,
+            length: edges.length,
+            totalWeight,
+        };
+    }
+    // ── Contradiction Detection ────────────────────────────────
+    /**
+     * Find all contradiction edges in the graph.
+     *
+     * Performance: Batch loads all memories in one query instead of
+     * 2×limit individual queries.
+     */
+    async findContradictions(limit = 20) {
+        const rows = await getPrismaClient().$queryRaw `SELECT from_id AS source_id, to_id AS target_id,
+        metadata->>'evidence' AS evidence, weight
+      FROM memory_edges WHERE edge_type = ${MemoryRelationType.CONTRADICTS}
+      ORDER BY weight DESC, created_at DESC LIMIT ${limit}`;
+        // Collect all unique memory IDs
+        const memoryIds = new Set();
+        for (const row of rows) {
+            memoryIds.add(row.source_id);
+            memoryIds.add(row.target_id);
+        }
+        // Batch load all memories
+        const memoryMap = await this.loadMemoriesByIds(Array.from(memoryIds));
+        // Build pairs
+        const pairs = [];
+        for (const row of rows) {
+            const m1 = memoryMap.get(row.source_id);
+            const m2 = memoryMap.get(row.target_id);
+            if (!m1 || !m2)
+                continue;
+            pairs.push({
+                memory1: m1,
+                memory2: m2,
+                evidence: row.evidence || "Contradiction detected via semantic analysis",
+            });
+        }
+        return pairs;
+    }
+    // ── Decision Chain ─────────────────────────────────────────
+    /**
+     * Follow the chain of decisions that led to a given memory.
+     * Traverses DERIVED_FROM, CAUSES, and SUPPORTS edges backwards.
+     */
+    async getDecisionChain(memoryId, maxDepth = 5) {
+        return this.getRelatedContext(memoryId, {
+            maxDepth,
+            relationTypes: [
+                MemoryRelationType.DERIVED_FROM,
+                MemoryRelationType.CAUSES,
+                MemoryRelationType.SUPPORTS,
+            ],
+            minWeight: 0.3,
+            limit: 20,
+            includeEvidence: true,
+        });
+    }
+    // ── Hub Analysis ───────────────────────────────────────────
+    /**
+     * Get the most connected memories (hubs) with full memory data.
+     *
+     * Performance: Batch loads all hub memories in one query instead of
+     * limit individual queries.
+     */
+    async getHubMemories(limit = 10) {
+        const hubs = await this.graphStore.getHubMemories(limit);
+        const memoryIds = hubs.map((h) => h.memoryId);
+        // Batch load all hub memories
+        const memoryMap = await this.loadMemoriesByIds(memoryIds);
+        const result = [];
+        for (const hub of hubs) {
+            const memory = memoryMap.get(hub.memoryId);
+            if (memory) {
+                result.push({ memory, degree: hub.degree });
+            }
+        }
+        return result;
+    }
+    // ── Neighborhood Summary ───────────────────────────────────
+    /**
+     * Get a compact summary of a memory's neighborhood.
+     * Useful for injecting into LLM context.
+     */
+    async getNeighborhoodSummary(memoryId) {
+        const related = await this.getRelatedContext(memoryId, {
+            maxDepth: 1,
+            limit: 10,
+        });
+        if (related.length === 0) {
+            return "";
+        }
+        const lines = ["Related memories:"];
+        for (const r of related) {
+            const direction = r.edge.sourceId === memoryId ? "→" : "←";
+            const typeLabel = r.edge.relationType.replace(/_/g, " ").toLowerCase();
+            const snippet = r.memory.content.length > 120
+                ? r.memory.content.substring(0, 120) + "..."
+                : r.memory.content;
+            lines.push(`  ${direction} [${typeLabel}] (${r.memory.type}) ${snippet}`);
+        }
+        return lines.join("\n");
+    }
+    // ── Helpers ────────────────────────────────────────────────
+    /**
+     * Load a single memory by ID.
+     */
+    async loadMemory(memoryId) {
+        const values = await this.loadMemoriesByIds([memoryId]);
+        return values.get(memoryId) ?? null;
+    }
+    /**
+     * Batch load multiple memories by IDs.
+     *
+     * This eliminates N+1 query pattern in BFS traversal.
+     * Instead of O(N) queries, we do O(1) per BFS level.
+     *
+     * Example: Loading 100 neighbors goes from 100 queries → 1 query.
+     */
+    async loadMemoriesByIds(memoryIds) {
+        if (memoryIds.length === 0) {
+            return new Map();
+        }
+        const rows = await getPrismaClient().$queryRaw `
+      SELECT id, content, type, level, importance, array_to_json(tags)::text AS tags,
+             created_at, updated_at, access_count, user_id, session_id, project_id, agent_id,
+             NULL::bytea AS embedding, NULL::text AS metadata, NULL::timestamp AS last_accessed,
+             pinned::integer AS pinned, deleted_at
+      FROM memories WHERE id = ANY(${memoryIds}::text[])`;
+        // Convert to map for O(1) lookup
+        const result = new Map();
+        for (const row of rows) {
+            result.set(row.id, { ...row, created_at: new Date(row.created_at).getTime(), updated_at: new Date(row.updated_at).getTime(), last_accessed: null, deleted_at: row.deleted_at ? new Date(row.deleted_at).getTime() : null });
+        }
+        return result;
+    }
+    /**
+     * Close database connection.
+     */
+    close() { }
+}
+//# sourceMappingURL=graph-queries.js.map

package/dist/services/graph/graph-queries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-queries.js","sourceRoot":"","sources":["../../../src/services/graph/graph-queries.ts"],"names":[],"mappings":"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"}

package/dist/services/graph/graph-store-factory.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Graph Store Factory
+ *
+ * Provides a unified `IGraphStore` implementation based on database
+ * configuration. Consumers call `getGraphStore()` and receive a
+ * backend-agnostic store — they never depend on the concrete PostgreSQL or
+ * PostgreSQL class (structural gap #14).
+ */
+import type { IGraphStore } from "./types.js";
+export declare function getGraphStore(): IGraphStore;
+export declare function resetGraphStore(): Promise<void>;
+//# sourceMappingURL=graph-store-factory.d.ts.map

package/dist/services/graph/graph-store-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-store-factory.d.ts","sourceRoot":"","sources":["../../../src/services/graph/graph-store-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAK9C,wBAAgB,aAAa,IAAI,WAAW,CAO3C;AAED,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CASrD"}

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

@@ -0,0 +1,30 @@
+/**
+ * Graph Store Factory
+ *
+ * Provides a unified `IGraphStore` implementation based on database
+ * configuration. Consumers call `getGraphStore()` and receive a
+ * backend-agnostic store — they never depend on the concrete PostgreSQL or
+ * PostgreSQL class (structural gap #14).
+ */
+import { GraphStorePg } from "./graph-store-pg.js";
+import { logger } from "@massa-ai/shared";
+let cachedStore = null;
+export function getGraphStore() {
+    if (cachedStore)
+        return cachedStore;
+    cachedStore = GraphStorePg.getInstance();
+    logger.info('Using PostgreSQL graph store');
+    return cachedStore;
+}
+export async function resetGraphStore() {
+    if (cachedStore) {
+        try {
+            await cachedStore.clear();
+        }
+        catch {
+            // Defensive: never block a reset on a clear failure.
+        }
+        cachedStore = null;
+    }
+}
+//# sourceMappingURL=graph-store-factory.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph-store-factory.js","sourceRoot":"","sources":["../../../src/services/graph/graph-store-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE1C,IAAI,WAAW,GAAuB,IAAI,CAAC;AAE3C,MAAM,UAAU,aAAa;IAC3B,IAAI,WAAW;QAAE,OAAO,WAAW,CAAC;IAEpC,WAAW,GAAG,YAAY,CAAC,WAAW,EAAE,CAAC;IACzC,MAAM,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;IAE5C,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe;IACnC,IAAI,WAAW,EAAE,CAAC;QAChB,IAAI,CAAC;YACH,MAAM,WAAW,CAAC,KAAK,EAAE,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,qDAAqD;QACvD,CAAC;QACD,WAAW,GAAG,IAAI,CAAC;IACrB,CAAC;AACH,CAAC"}

package/dist/services/graph/graph-store-pg.d.ts

@@ -0,0 +1,127 @@
+/**
+ * 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 { MemoryEdge, MemoryRelationType } from "@massa-ai/shared";
+import type { EdgeCreateInput, EdgeFilter, IGraphStore } from "./types.js";
+export declare class GraphStorePg implements IGraphStore {
+    private static instance;
+    static getInstance(): GraphStorePg;
+    constructor();
+    /**
+     * 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.
+     */
+    createEdge(edge: EdgeCreateInput): Promise<MemoryEdge | null>;
+    /**
+     * Get edge by (sourceId, targetId, relationType) triple.
+     * IGraphStore-conformant alias; the PG schema stores edges by from/to/type.
+     */
+    getEdge(sourceId: string, targetId: string, relationType: MemoryRelationType): Promise<MemoryEdge | null>;
+    /**
+     * Find edges matching filters.
+     * Kept as a non-contract helper (contract callers use getAllEdges).
+     */
+    findEdges(filter: EdgeFilter): Promise<MemoryEdge[]>;
+    /**
+     * Get all edges from a source memory.
+     * Not on the contract; used internally by bfsNeighbors.
+     */
+    getOutgoingEdges(sourceId: string, limit?: number): Promise<MemoryEdge[]>;
+    /**
+     * Get all edges to a target memory.
+     */
+    getIncomingEdges(targetId: string, limit?: number): Promise<MemoryEdge[]>;
+    /**
+     * Phase 7c: async BFS over outgoing edges (mirror of GraphStore.bfsNeighbors).
+     */
+    bfsNeighbors(seedIds: string[], depth: number): Promise<string[]>;
+    /**
+     * Get all edges connected to a memory (both incoming and outgoing).
+     * IGraphStore-conformant; replaces the legacy `getConnectedEdges` name.
+     */
+    getAllEdges(memoryId: string, filter?: EdgeFilter): Promise<MemoryEdge[]>;
+    /**
+     * Update edge weight (set). IGraphStore-conformant alias for updateEdgeWeight.
+     */
+    updateWeight(id: string, weight: number): Promise<boolean>;
+    /**
+     * Legacy alias kept for callers that used the PG-specific name.
+     */
+    updateEdgeWeight(id: string, weight: number): Promise<boolean>;
+    /**
+     * Atomically increment edge weight by delta, capped at maxWeight.
+     * IGraphStore-conformant; the single UPDATE prevents lost increments when
+     * multiple reinforcement calls race.
+     */
+    incrementEdgeWeight(sourceId: string, targetId: string, relationType: MemoryRelationType, delta: number, maxWeight?: number): Promise<boolean>;
+    /**
+     * Delete an edge by ID.
+     */
+    deleteEdge(id: string): Promise<boolean>;
+    /**
+     * Delete all edges connected to a memory.
+     * IGraphStore-conformant alias; replaces the legacy `deleteEdgesByMemory` name.
+     */
+    deleteEdgesForMemory(memoryId: string): Promise<number>;
+    /**
+     * Legacy alias kept for callers that used the PG-specific name.
+     */
+    deleteEdgesByMemory(memoryId: string): Promise<number>;
+    /**
+     * Batch create edges.
+     */
+    batchCreateEdges(edges: EdgeCreateInput[]): Promise<number>;
+    /**
+     * Degree centrality for a memory (in + out + total).
+     * IGraphStore-conformant.
+     */
+    getDegree(memoryId: string): Promise<{
+        in: number;
+        out: number;
+        total: number;
+    }>;
+    /**
+     * 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.
+     */
+    getHubMemories(limit?: number): Promise<{
+        memoryId: string;
+        degree: number;
+    }[]>;
+    /**
+     * Get statistics about the graph.
+     * IGraphStore-conformant alias for getGraphStats, normalizing the return
+     * shape to match the PostgreSQL store (byRelation/autoExtracted/avgWeight).
+     */
+    getStats(): Promise<{
+        totalEdges: number;
+        byRelation: Record<string, number>;
+        autoExtracted: number;
+        avgWeight: number;
+    }>;
+    /**
+     * Find paths between two memories (BFS, up to maxDepth)
+     */
+    findPaths(fromId: string, toId: string, maxDepth?: number): Promise<Array<{
+        path: string[];
+        weight: number;
+    }>>;
+    /**
+     * Clear all edges (for testing)
+     */
+    clear(): Promise<void>;
+}
+export declare const graphStorePg: GraphStorePg;
+//# sourceMappingURL=graph-store-pg.d.ts.map

package/dist/services/graph/graph-store-pg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-store-pg.d.ts","sourceRoot":"","sources":["../../../src/services/graph/graph-store-pg.ts"],"names":[],"mappings":"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"}