@ai.ntellect/core 0.8.3 → 1.1.0

package/persistence/index.ts

@@ -0,0 +1,27 @@
+export { Memory } from "../modules/memory";
+export { InMemoryCheckpointAdapter } from "../execution/adapters/in-memory-checkpoint";
+export {
+  IPetriCheckpointAdapter,
+  InMemoryPetriCheckpointAdapter,
+} from "../routing/checkpoint-adapter";
+export { RedisPetriCheckpointAdapter } from "../routing/redis-checkpoint-adapter";
+export { PostgresPetriCheckpointAdapter } from "../routing/postgres-checkpoint-adapter";
+export {
+  Neo4jExecutionTracer,
+} from "./neo4j/execution-tracer";
+export {
+  Neo4jPetriCheckpointAdapter,
+} from "./neo4j/petri-checkpoint-adapter";
+export {
+  Neo4jMemoryAdapter,
+} from "./neo4j/memory-adapter";
+export {
+  Neo4jEntityStore,
+  IEntityStore,
+} from "./neo4j/entity-store";
+export type {
+  Neo4jConfig,
+  Neo4jDriverLike,
+  Neo4jSessionLike,
+} from "./neo4j/driver";
+export { createDriver } from "./neo4j/driver";

package/persistence/neo4j/driver.ts

@@ -0,0 +1,34 @@
+export interface Neo4jSessionLike {
+  run(query: string, params?: Record<string, any>): Promise<{ records: any[] }>;
+  close(): Promise<void>;
+}
+
+export interface Neo4jDriverLike {
+  session(config?: { database?: string }): Neo4jSessionLike;
+  close(): Promise<void>;
+}
+
+export type Neo4jConfig =
+  | { driver: Neo4jDriverLike; database?: string }
+  | { url: string; username: string; password: string; database?: string };
+
+export async function createDriver(config: Neo4jConfig): Promise<{ driver: Neo4jDriverLike; database?: string }> {
+  if ("driver" in config) {
+    return { driver: config.driver, database: config.database };
+  }
+
+  let neo4j: any;
+  try {
+    neo4j = await import("neo4j-driver");
+  } catch {
+    throw new Error(
+      "neo4j-driver is not installed. Install it with: npm install neo4j-driver"
+    );
+  }
+
+  const driver = neo4j.default.auth
+    ? neo4j.default.driver(config.url, neo4j.default.auth.basic(config.username, config.password))
+    : neo4j.default.driver(config.url, neo4j.default.auth.basic(config.username, config.password));
+
+  return { driver, database: config.database };
+}

package/persistence/neo4j/entity-store.ts

@@ -0,0 +1,141 @@
+import { Entity } from "../../agent/entity-resolver/types";
+import { IEntityStore } from "../../agent/entity-resolver/entity-index";
+import { Neo4jDriverLike, Neo4jSessionLike } from "./driver";
+
+export { IEntityStore };
+
+export class Neo4jEntityStore implements IEntityStore {
+  constructor(
+    private driver: Neo4jDriverLike,
+    private database?: string
+  ) {}
+
+  private session(): Neo4jSessionLike {
+    return this.driver.session(this.database ? { database: this.database } : undefined);
+  }
+
+  async upsertMany(entities: Entity[]): Promise<void> {
+    const s = this.session();
+    try {
+      for (const entity of entities) {
+        await s.run(
+          `MERGE (e:Entity {id: $id})
+           SET e.category = $category,
+               e.filename = $filename,
+               e.stem = $stem,
+               e.extension = $extension,
+               e.path = $path,
+               e.scope = $scope
+           WITH e
+           UNWIND $tokens AS tokenValue
+           MERGE (t:Token {value: tokenValue})
+           MERGE (e)-[:HAS_TOKEN]->(t)`,
+          {
+            id: entity.id,
+            category: entity.category,
+            filename: entity.filename,
+            stem: entity.stem,
+            extension: entity.extension,
+            path: entity.path,
+            scope: entity.path.split("/")[0] || "root",
+            tokens: entity.tokens,
+          }
+        );
+
+        const dir = entity.path.substring(0, entity.path.lastIndexOf("/")) || "/";
+        await s.run(
+          `MATCH (e:Entity {id: $id})
+           MERGE (d:Dir {path: $dir})
+           MERGE (e)-[:IN_DIR]->(d)`,
+          { id: entity.id, dir }
+        );
+      }
+    } finally {
+      await s.close();
+    }
+  }
+
+  async loadAll(scope?: string): Promise<Entity[]> {
+    const s = this.session();
+    try {
+      let query: string;
+      let params: Record<string, any> = {};
+
+      if (scope) {
+        query = `MATCH (e:Entity)
+                 WHERE e.scope = $scope
+                 OPTIONAL MATCH (e)-[:HAS_TOKEN]->(t:Token)
+                 RETURN e, collect(t.value) AS tokens
+                 ORDER BY e.filename`;
+        params.scope = scope;
+      } else {
+        query = `MATCH (e:Entity)
+                 OPTIONAL MATCH (e)-[:HAS_TOKEN]->(t:Token)
+                 RETURN e, collect(t.value) AS tokens
+                 ORDER BY e.filename`;
+      }
+
+      const result = await s.run(query, params);
+
+      return result.records.map((r: any) => {
+        const entity = r.get("e");
+        const props = entity.properties ? (typeof entity.properties === "function" ? entity.properties() : entity.properties) : entity;
+        return {
+          id: props.id,
+          category: props.category || "file",
+          filename: props.filename,
+          stem: props.stem,
+          extension: props.extension || null,
+          tokens: r.get("tokens") || [],
+          path: props.path,
+        } as Entity;
+      });
+    } finally {
+      await s.close();
+    }
+  }
+
+  async recordResolution(
+    entityId: string,
+    query: string,
+    confidence: number
+  ): Promise<void> {
+    const s = this.session();
+    try {
+      await s.run(
+        `MATCH (e:Entity {id: $entityId})
+         CREATE (r:Resolution {id: $resolutionId, query: $query, confidence: $confidence, at: $at})
+         MERGE (e)-[:RESOLVED_BY]->(r)`,
+        {
+          entityId,
+          resolutionId: `res-${entityId}-${Date.now()}`,
+          query,
+          confidence,
+          at: new Date().toISOString(),
+        }
+      );
+    } finally {
+      await s.close();
+    }
+  }
+
+  async clear(scope?: string): Promise<void> {
+    const s = this.session();
+    try {
+      if (scope) {
+        await s.run(
+          `MATCH (e:Entity {scope: $scope})
+           DETACH DELETE e`,
+          { scope }
+        );
+      } else {
+        await s.run(
+          `MATCH (e:Entity)
+           DETACH DELETE e`
+        );
+      }
+    } finally {
+      await s.close();
+    }
+  }
+}

package/persistence/neo4j/execution-tracer.ts

@@ -0,0 +1,194 @@
+import { ZodSchema } from "zod";
+import { GraphFlow } from "../../execution";
+import { Neo4jDriverLike, Neo4jSessionLike } from "./driver";
+
+export class Neo4jExecutionTracer {
+  private driver: Neo4jDriverLike;
+  private database?: string;
+  private unsubscribeFns: Array<() => void> = [];
+  private executionId: string;
+
+  private constructor(
+    driver: Neo4jDriverLike,
+    executionId: string,
+    database?: string
+  ) {
+    this.driver = driver;
+    this.executionId = executionId;
+    this.database = database;
+  }
+
+  static attach<T extends ZodSchema>(
+    graph: GraphFlow<T>,
+    driver: Neo4jDriverLike,
+    executionId?: string,
+    database?: string
+  ): Neo4jExecutionTracer {
+    const id = executionId || crypto.randomUUID();
+    const tracer = new Neo4jExecutionTracer(driver, id, database);
+
+    const onStarted = (data: any) => {
+      tracer.onNodeStarted(data).catch(() => {});
+    };
+    graph.on("nodeStarted", onStarted);
+    tracer.unsubscribeFns.push(() => {
+      if (typeof (graph as any).removeListener === "function") {
+        (graph as any).removeListener("nodeStarted", onStarted);
+      } else if (typeof (graph as any).off === "function") {
+        (graph as any).off("nodeStarted", onStarted);
+      }
+    });
+
+    const onCompleted = (data: any) => {
+      tracer.onNodeCompleted(data).catch(() => {});
+    };
+    graph.on("nodeCompleted", onCompleted);
+    tracer.unsubscribeFns.push(() => {
+      if (typeof (graph as any).removeListener === "function") {
+        (graph as any).removeListener("nodeCompleted", onCompleted);
+      } else if (typeof (graph as any).off === "function") {
+        (graph as any).off("nodeCompleted", onCompleted);
+      }
+    });
+
+    const onError = (data: any) => {
+      tracer.onNodeError(data).catch(() => {});
+    };
+    graph.on("nodeError", onError);
+    tracer.unsubscribeFns.push(() => {
+      if (typeof (graph as any).removeListener === "function") {
+        (graph as any).removeListener("nodeError", onError);
+      } else if (typeof (graph as any).off === "function") {
+        (graph as any).off("nodeError", onError);
+      }
+    });
+
+    return tracer;
+  }
+
+  getExecutionId(): string {
+    return this.executionId;
+  }
+
+  detach(): void {
+    for (const fn of this.unsubscribeFns) {
+      fn();
+    }
+    this.unsubscribeFns = [];
+  }
+
+  async initExecution(
+    graphName: string,
+    startedAt: Date = new Date()
+  ): Promise<void> {
+    const session = this.driver.session(this.database ? { database: this.database } : undefined);
+    try {
+      await session.run(
+        `MERGE (e:Execution {id: $id})
+         SET e.graphName = $graphName,
+             e.startedAt = $startedAt,
+             e.status = "running"`,
+        { id: this.executionId, graphName, startedAt: startedAt.toISOString() }
+      );
+    } finally {
+      await session.close();
+    }
+  }
+
+  async completeExecution(
+    status: "completed" | "failed" = "completed",
+    completedAt: Date = new Date()
+  ): Promise<void> {
+    const session = this.driver.session(this.database ? { database: this.database } : undefined);
+    try {
+      await session.run(
+        `MATCH (e:Execution {id: $id})
+         SET e.status = $status,
+             e.completedAt = $completedAt`,
+        { id: this.executionId, status, completedAt: completedAt.toISOString() }
+      );
+    } finally {
+      await session.close();
+    }
+  }
+
+  private async onNodeStarted(data: {
+    name?: string;
+    payload?: { name?: string };
+  }): Promise<void> {
+    const name = data.name || data.payload?.name || "unknown";
+    const nodeRunId = `${this.executionId}-${name}`;
+
+    const session = this.driver.session(this.database ? { database: this.database } : undefined);
+    try {
+      await session.run(
+        `MATCH (e:Execution {id: $executionId})
+         MERGE (n:NodeRun {id: $nodeRunId})
+         SET n.name = $name,
+             n.startedAt = $startedAt,
+             n.status = "running"
+         MERGE (e)-[:HAS_RUN]->(n)`,
+        {
+          executionId: this.executionId,
+          nodeRunId,
+          name,
+          startedAt: new Date().toISOString(),
+        }
+      );
+    } finally {
+      await session.close();
+    }
+  }
+
+  private async onNodeCompleted(data: {
+    name?: string;
+    payload?: { name?: string; context?: any };
+  }): Promise<void> {
+    const name = data.name || data.payload?.name || "unknown";
+    const nodeRunId = `${this.executionId}-${name}`;
+
+    const session = this.driver.session(this.database ? { database: this.database } : undefined);
+    try {
+      await session.run(
+        `MATCH (n:NodeRun {id: $nodeRunId})
+         SET n.status = "completed",
+             n.completedAt = $completedAt`,
+        {
+          nodeRunId,
+          completedAt: new Date().toISOString(),
+        }
+      );
+    } finally {
+      await session.close();
+    }
+  }
+
+  private async onNodeError(data: {
+    name?: string;
+    payload?: { name?: string; error?: any };
+  }): Promise<void> {
+    const name = data.name || data.payload?.name || "unknown";
+    const nodeRunId = `${this.executionId}-${name}`;
+    const errorMessage =
+      data.payload?.error?.message ||
+      data.payload?.error?.toString() ||
+      "Unknown error";
+
+    const session = this.driver.session(this.database ? { database: this.database } : undefined);
+    try {
+      await session.run(
+        `MATCH (n:NodeRun {id: $nodeRunId})
+         SET n.status = "error",
+             n.error = $error,
+             n.completedAt = $completedAt`,
+        {
+          nodeRunId,
+          error: errorMessage,
+          completedAt: new Date().toISOString(),
+        }
+      );
+    } finally {
+      await session.close();
+    }
+  }
+}

package/persistence/neo4j/memory-adapter.ts

@@ -0,0 +1,281 @@
+import { IGraphMemoryAdapter, MemoryRelation } from "../../interfaces";
+import {
+  BaseMemoryType,
+  CreateMemoryInput,
+} from "../../types";
+import { Neo4jDriverLike, Neo4jSessionLike } from "./driver";
+
+export class Neo4jMemoryAdapter implements IGraphMemoryAdapter {
+  constructor(
+    private driver: Neo4jDriverLike,
+    private database?: string
+  ) {}
+
+  private session(): Neo4jSessionLike {
+    return this.driver.session(this.database ? { database: this.database } : undefined);
+  }
+
+  async init(roomId?: string): Promise<void> {
+    if (!roomId) return;
+    const s = this.session();
+    try {
+      await s.run(
+        `MERGE (:Room {id: $roomId})`,
+        { roomId }
+      );
+    } finally {
+      await s.close();
+    }
+  }
+
+  async createMemory(
+    input: CreateMemoryInput & { embedding?: number[] }
+  ): Promise<BaseMemoryType | undefined> {
+    const memory: BaseMemoryType = {
+      id: input.id || crypto.randomUUID(),
+      content: input.content,
+      metadata: input.metadata,
+      embedding: input.embedding,
+      roomId: input.roomId,
+      createdAt: new Date(),
+    };
+
+    const s = this.session();
+    try {
+      await s.run(
+        `MERGE (r:Room {id: $roomId})
+         CREATE (m:Memory {
+           id: $id,
+           content: $content,
+           createdAt: $createdAt,
+           metadata: $metadata
+         })
+         MERGE (m)-[:IN_ROOM]->(r)
+         RETURN m`,
+        {
+          roomId: memory.roomId,
+          id: memory.id,
+          content: memory.content,
+          createdAt: memory.createdAt.toISOString(),
+          metadata: memory.metadata ? JSON.stringify(memory.metadata) : null,
+        }
+      );
+
+      if (memory.embedding) {
+        try {
+          await s.run(
+            `MATCH (m:Memory {id: $id})
+             SET m.embedding = $embedding`,
+            { id: memory.id, embedding: memory.embedding }
+          );
+        } catch {
+          // vector index may not exist; embedding stored as best-effort
+        }
+      }
+
+      return memory;
+    } finally {
+      await s.close();
+    }
+  }
+
+  async getMemoryById(
+    id: string,
+    roomId: string
+  ): Promise<BaseMemoryType | null> {
+    const s = this.session();
+    try {
+      const result = await s.run(
+        `MATCH (m:Memory {id: $id})-[:IN_ROOM]->(:Room {id: $roomId})
+         RETURN m`,
+        { id, roomId }
+      );
+
+      if (result.records.length === 0) return null;
+      return this.recordToMemory(result.records[0].get("m"));
+    } finally {
+      await s.close();
+    }
+  }
+
+  async getMemoryByIndex(
+    query: string,
+    options: { roomId: string; limit?: number }
+  ): Promise<BaseMemoryType[]> {
+    const s = this.session();
+    try {
+      const result = await s.run(
+        `CALL db.index.fulltext.queryNodes("memory_content", $query)
+         YIELD node AS m, score
+         WHERE (m)-[:IN_ROOM]->(:Room {id: $roomId})
+         RETURN m, score
+         ORDER BY score DESC
+         LIMIT toInteger($limit)`,
+        {
+          query,
+          roomId: options.roomId,
+          limit: options.limit || 10,
+        }
+      );
+
+      return result.records.map((r: any) => this.recordToMemory(r.get("m")));
+    } catch {
+      const result = await s.run(
+        `MATCH (m:Memory)-[:IN_ROOM]->(:Room {id: $roomId})
+         WHERE m.content CONTAINS $query
+         RETURN m
+         LIMIT toInteger($limit)`,
+        {
+          roomId: options.roomId,
+          query,
+          limit: options.limit || 10,
+        }
+      );
+      return result.records.map((r: any) => this.recordToMemory(r.get("m")));
+    } finally {
+      await s.close();
+    }
+  }
+
+  async getAllMemories(roomId: string): Promise<BaseMemoryType[]> {
+    const s = this.session();
+    try {
+      const result = await s.run(
+        `MATCH (m:Memory)-[:IN_ROOM]->(:Room {id: $roomId})
+         RETURN m
+         ORDER BY m.createdAt DESC`,
+        { roomId }
+      );
+
+      return result.records.map((r: any) => this.recordToMemory(r.get("m")));
+    } finally {
+      await s.close();
+    }
+  }
+
+  async clearMemoryById(id: string, roomId: string): Promise<void> {
+    const s = this.session();
+    try {
+      await s.run(
+        `MATCH (m:Memory {id: $id})-[:IN_ROOM]->(:Room {id: $roomId})
+         DETACH DELETE m`,
+        { id, roomId }
+      );
+    } finally {
+      await s.close();
+    }
+  }
+
+  async clearAllMemories(): Promise<void> {
+    const s = this.session();
+    try {
+      await s.run(`MATCH (m:Memory) DETACH DELETE m`);
+    } finally {
+      await s.close();
+    }
+  }
+
+  async addRelation(relation: MemoryRelation): Promise<void> {
+    const s = this.session();
+    try {
+      await s.run(
+        `MATCH (from:Memory {id: $fromId})
+         MATCH (to:Memory {id: $toId})
+         MERGE (from)-[r:RELATES_TO {type: $type}]->(to)
+         SET r.weight = $weight,
+             r.createdAt = $createdAt`,
+        {
+          fromId: relation.fromId,
+          toId: relation.toId,
+          type: relation.type,
+          weight: relation.properties?.weight ?? 1,
+          createdAt: new Date().toISOString(),
+        }
+      );
+    } finally {
+      await s.close();
+    }
+  }
+
+  async removeRelation(
+    fromId: string,
+    toId: string,
+    type: string,
+    _roomId: string
+  ): Promise<void> {
+    const s = this.session();
+    try {
+      await s.run(
+        `MATCH (from:Memory {id: $fromId})-[r:RELATES_TO {type: $type}]->(to:Memory {id: $toId})
+         DELETE r`,
+        { fromId, toId, type }
+      );
+    } finally {
+      await s.close();
+    }
+  }
+
+  async getRelated(
+    id: string,
+    options: {
+      roomId: string;
+      relationTypes?: string[];
+      direction?: "in" | "out" | "both";
+      depth?: number;
+      limit?: number;
+    }
+  ): Promise<Array<{ memory: BaseMemoryType; relationPath: string[] }>> {
+    const depth = options.depth ?? 1;
+    const direction = options.direction ?? "both";
+    const limit = options.limit ?? 10;
+
+    let directionPattern: string;
+    if (direction === "out") directionPattern = "(m:Memory)-[r:RELATES_TO]->(related)";
+    else if (direction === "in") directionPattern = "(m:Memory)<-[r:RELATES_TO]-(related)";
+    else directionPattern = "(m:Memory)-[r:RELATES_TO]-(related)";
+
+    let typeFilter = "";
+    if (options.relationTypes && options.relationTypes.length > 0) {
+      const types = options.relationTypes.map(t => `r.type = "${t}"`).join(" OR ");
+      typeFilter = `AND (${types})`;
+    }
+
+    const s = this.session();
+    try {
+      const query = depth === 1
+        ? `MATCH ${directionPattern}
+           WHERE m.id = $id ${typeFilter}
+           RETURN DISTINCT related AS related, [] AS path
+           LIMIT toInteger($limit)`
+        : `MATCH (m:Memory {id: $id})
+           CALL {
+             MATCH (m)-[r:RELATES_TO*1..${depth}]-(related:Memory)
+             WHERE m.id <> related.id ${typeFilter ? `AND ${typeFilter.replace(/r\./g, "r0.")}` : ""}
+             RETURN DISTINCT related, [r IN r | r.type] AS path
+           }
+           RETURN related, path
+           LIMIT toInteger($limit)`;
+
+      const result = await s.run(query, { id, limit });
+
+      return result.records.map((r: any) => ({
+        memory: this.recordToMemory(r.get("related")),
+        relationPath: r.get("path") || [],
+      }));
+    } finally {
+      await s.close();
+    }
+  }
+
+  private recordToMemory(record: any): BaseMemoryType {
+    const props = record.properties ? (typeof record.properties === "function" ? record.properties() : record.properties) : record;
+    return {
+      id: props.id,
+      content: props.content,
+      metadata: props.metadata ? (typeof props.metadata === "string" ? JSON.parse(props.metadata) : props.metadata) : undefined,
+      embedding: props.embedding,
+      roomId: props.roomId,
+      createdAt: new Date(props.createdAt),
+    };
+  }
+}