wolbarg 0.4.0 → 0.5.0

package/dist/index.cjs

@@ -1,9 +1,9 @@
 'use strict';
 
-var path5 = require("node:path");
+var fs6 = require("node:fs");
+var path7 = require("node:path");
 var crypto$1 = require('crypto');
 var fs = require('fs/promises');
-var fs5 = require("node:fs");
 var sqlite$1 = require("node:sqlite");
 var sqliteVec = require('sqlite-vec');
 var async_hooks = require('async_hooks');
@@ -29,9 +29,9 @@ function _interopNamespace(e) {
   return Object.freeze(n);
 }
 
-var path5__default = /*#__PURE__*/_interopDefault(path5);
+var fs6__default = /*#__PURE__*/_interopDefault(fs6);
+var path7__default = /*#__PURE__*/_interopDefault(path7);
 var fs__default = /*#__PURE__*/_interopDefault(fs);
-var fs5__default = /*#__PURE__*/_interopDefault(fs5);
 var sqliteVec__namespace = /*#__PURE__*/_interopNamespace(sqliteVec);
 
 // src/core/wolbarg.ts
@@ -112,6 +112,20 @@ var ProviderNotConfiguredError = class extends ConfigurationError {
     this.provider = provider;
   }
 };
+var GraphCheckpointNotSupportedError = class extends WolbargError {
+  constructor(backend, operation) {
+    super(
+      `graph checkpoint not supported for network-backed graph providers (${backend})`,
+      "GRAPH_CHECKPOINT_NOT_SUPPORTED",
+      {
+        operation,
+        reason: `${backend} is networked / not file-backed`,
+        suggestion: "Use sqliteGraph({ path }) for local snapshots, or checkpoint memory storage only without a network graph provider."
+      }
+    );
+    this.name = "GraphCheckpointNotSupportedError";
+  }
+};
 function wrapOperationError(operation, error) {
   if (error instanceof WolbargError) {
     return error;
@@ -412,9 +426,9 @@ var AsyncMutex = class {
     }
   }
 };
-function joinUrl(baseUrl, path7) {
+function joinUrl(baseUrl, path8) {
   const base = baseUrl.replace(/\/+$/, "");
-  const suffix = path7.startsWith("/") ? path7 : `/${path7}`;
+  const suffix = path8.startsWith("/") ? path8 : `/${path8}`;
   return `${base}${suffix}`;
 }
 
@@ -1109,7 +1123,7 @@ function extOf(filename) {
   if (!filename) {
     return "";
   }
-  return path5__default.default.extname(filename).toLowerCase();
+  return path7__default.default.extname(filename).toLowerCase();
 }
 var TextParser = class {
   name = "text";
@@ -1254,7 +1268,7 @@ async function loadIngestSource(source) {
     const buffer = await fs__default.default.readFile(source.path);
     return {
       buffer,
-      filename: path5__default.default.basename(source.path),
+      filename: path7__default.default.basename(source.path),
       mimeType: source.mimeType
     };
   }
@@ -1274,6 +1288,9 @@ function isStorageProvider(value) {
 function isTelemetryProvider(value) {
   return typeof value.emit === "function";
 }
+function isGraphProvider(value) {
+  return typeof value.open === "function" && typeof value.linkMemories === "function" && typeof value.getRelated === "function";
+}
 function resolveDatabaseUrl(config) {
   const url = "url" in config && config.url || "connectionString" in config && config.connectionString || "";
   return typeof url === "string" ? url : "";
@@ -1344,11 +1361,11 @@ function jsonPath(field) {
   return `$.${field}`;
 }
 function compileComparison(field, op) {
-  const path7 = jsonPath(field);
-  if (!path7) {
+  const path8 = jsonPath(field);
+  if (!path8) {
     return null;
   }
-  const extract = `json_extract(metadata_json, '${path7}')`;
+  const extract = `json_extract(metadata_json, '${path8}')`;
   if ("eq" in op) {
     const value = op.eq;
     if (value !== null && typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
@@ -1493,6 +1510,40 @@ CREATE TABLE IF NOT EXISTS embedding_cache (
   last_used_at TEXT NOT NULL
 );
 `;
+var CREATE_GRAPH_NODES_TABLE = `
+CREATE TABLE IF NOT EXISTS graph_nodes (
+  id TEXT PRIMARY KEY NOT NULL,
+  type TEXT NOT NULL CHECK (type IN ('memory', 'entity')),
+  ref_id TEXT NOT NULL,
+  name TEXT NULL,
+  metadata TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL
+);
+`;
+var CREATE_GRAPH_EDGES_TABLE = `
+CREATE TABLE IF NOT EXISTS graph_edges (
+  id TEXT PRIMARY KEY NOT NULL,
+  from_node_id TEXT NOT NULL,
+  to_node_id TEXT NOT NULL,
+  relation TEXT NOT NULL,
+  metadata TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL,
+  FOREIGN KEY (from_node_id) REFERENCES graph_nodes(id) ON DELETE CASCADE,
+  FOREIGN KEY (to_node_id) REFERENCES graph_nodes(id) ON DELETE CASCADE
+);
+`;
+var CREATE_GRAPH_INDEXES = [
+  `CREATE UNIQUE INDEX IF NOT EXISTS idx_graph_nodes_type_ref
+     ON graph_nodes(type, ref_id);`,
+  `CREATE INDEX IF NOT EXISTS idx_graph_edges_from
+     ON graph_edges(from_node_id);`,
+  `CREATE INDEX IF NOT EXISTS idx_graph_edges_to
+     ON graph_edges(to_node_id);`,
+  `CREATE INDEX IF NOT EXISTS idx_graph_edges_from_rel
+     ON graph_edges(from_node_id, relation);`,
+  `CREATE INDEX IF NOT EXISTS idx_graph_edges_to_rel
+     ON graph_edges(to_node_id, relation);`
+];
 var CREATE_INDEXES = [
   `CREATE INDEX IF NOT EXISTS idx_memories_org_agent ON memories(organization, agent);`,
   `CREATE INDEX IF NOT EXISTS idx_memories_org_archived ON memories(organization, archived);`,
@@ -2093,7 +2144,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
       const dbPath = this.resolvePath(this.connectionString);
       this.resolvedPath = dbPath;
       if (dbPath !== ":memory:") {
-        fs5__default.default.mkdirSync(path5__default.default.dirname(dbPath), { recursive: true });
+        fs6__default.default.mkdirSync(path7__default.default.dirname(dbPath), { recursive: true });
       }
       const db = new sqlite$1.DatabaseSync(dbPath, { allowExtension: true });
       this.db = db;
@@ -2581,11 +2632,11 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
     }
     const dbPath = this.resolvedPath ?? this.resolvePath(this.connectionString);
     try {
-      let total = fs5__default.default.statSync(dbPath).size;
+      let total = fs6__default.default.statSync(dbPath).size;
       for (const suffix of ["-wal", "-shm"]) {
         const side = `${dbPath}${suffix}`;
-        if (fs5__default.default.existsSync(side)) {
-          total += fs5__default.default.statSync(side).size;
+        if (fs6__default.default.existsSync(side)) {
+          total += fs6__default.default.statSync(side).size;
         }
       }
       return total;
@@ -3361,7 +3412,7 @@ var SqliteStorageProvider = class _SqliteStorageProvider {
     if (connectionString === ":memory:") {
       return ":memory:";
     }
-    return path5__default.default.isAbsolute(connectionString) ? connectionString : path5__default.default.resolve(process.cwd(), connectionString);
+    return path7__default.default.isAbsolute(connectionString) ? connectionString : path7__default.default.resolve(process.cwd(), connectionString);
   }
   requireDb() {
     if (!this.db) {
@@ -3412,8 +3463,8 @@ function jsonbTextExtract(field) {
   if (parts.length === 1) {
     return `metadata_json->>'${parts[0]}'`;
   }
-  const path7 = parts.join(",");
-  return `metadata_json #>> '{${path7}}'`;
+  const path8 = parts.join(",");
+  return `metadata_json #>> '{${path8}}'`;
 }
 function jsonbContainment(field, value, paramIndex) {
   if (!FIELD_RE2.test(field)) {
@@ -5112,7 +5163,11 @@ function createStorageProvider(config, options) {
 function createDatabaseProvider(config) {
   return createStorageProvider(config);
 }
-var SDK_VERSION = "0.3.0";
+
+// src/version.ts
+var SDK_VERSION = "0.5.0";
+
+// src/memory/transfer.ts
 var SqliteMemoryTransferProvider = class {
   async exportTo(exportPath, sourcePath, organization) {
     const resolvedSource = resolvePath(sourcePath);
@@ -5121,7 +5176,7 @@ var SqliteMemoryTransferProvider = class {
         "Cannot export an in-memory database. Use a file-backed SQLite database."
       );
     }
-    if (!fs5__default.default.existsSync(resolvedSource)) {
+    if (!fs6__default.default.existsSync(resolvedSource)) {
       throw new DatabaseError(
         `Failed to execute export()
 Reason:
@@ -5131,7 +5186,7 @@ Initialize Wolbarg and verify the database path.`
       );
     }
     const resolvedExport = resolvePath(exportPath);
-    fs5__default.default.mkdirSync(path5__default.default.dirname(resolvedExport), { recursive: true });
+    fs6__default.default.mkdirSync(path7__default.default.dirname(resolvedExport), { recursive: true });
     const dbExportPath = resolvedExport.endsWith(".db") ? resolvedExport : `${resolvedExport}.db`;
     const manifestPath = `${dbExportPath}.manifest.json`;
     await copySqlite(resolvedSource, dbExportPath);
@@ -5143,17 +5198,17 @@ Initialize Wolbarg and verify the database path.`
       sourcePath: resolvedSource,
       organization
     };
-    fs5__default.default.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf8");
+    fs6__default.default.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf8");
     return {
       path: dbExportPath,
       manifest,
-      sizeBytes: fs5__default.default.statSync(dbExportPath).size
+      sizeBytes: fs6__default.default.statSync(dbExportPath).size
     };
   }
   async importFrom(exportPath, targetPath) {
     const resolvedExport = resolvePath(exportPath);
-    const dbExportPath = resolvedExport.endsWith(".db") ? resolvedExport : fs5__default.default.existsSync(`${resolvedExport}.db`) ? `${resolvedExport}.db` : resolvedExport;
-    if (!fs5__default.default.existsSync(dbExportPath)) {
+    const dbExportPath = resolvedExport.endsWith(".db") ? resolvedExport : fs6__default.default.existsSync(`${resolvedExport}.db`) ? `${resolvedExport}.db` : resolvedExport;
+    if (!fs6__default.default.existsSync(dbExportPath)) {
       throw new ValidationError(
         `Failed to execute import()
 Reason:
@@ -5164,8 +5219,8 @@ Pass the path returned by export().`
     }
     const manifestPath = `${dbExportPath}.manifest.json`;
     let manifest;
-    if (fs5__default.default.existsSync(manifestPath)) {
-      manifest = JSON.parse(fs5__default.default.readFileSync(manifestPath, "utf8"));
+    if (fs6__default.default.existsSync(manifestPath)) {
+      manifest = JSON.parse(fs6__default.default.readFileSync(manifestPath, "utf8"));
       if (manifest.format !== "wolbarg-export-v1") {
         throw new ValidationError(
           `Unsupported export format: ${String(manifest.format)}`
@@ -5186,8 +5241,8 @@ Pass the path returned by export().`
     }
     for (const suffix of ["", "-wal", "-shm"]) {
       const side = `${resolvedTarget}${suffix}`;
-      if (fs5__default.default.existsSync(side)) {
-        fs5__default.default.rmSync(side, { force: true });
+      if (fs6__default.default.existsSync(side)) {
+        fs6__default.default.rmSync(side, { force: true });
       }
     }
     await copySqlite(dbExportPath, resolvedTarget);
@@ -5195,7 +5250,7 @@ Pass the path returned by export().`
   }
 };
 async function copySqlite(sourcePath, destPath) {
-  fs5__default.default.mkdirSync(path5__default.default.dirname(destPath), { recursive: true });
+  fs6__default.default.mkdirSync(path7__default.default.dirname(destPath), { recursive: true });
   let source = null;
   let dest = null;
   try {
@@ -5213,7 +5268,7 @@ async function copySqlite(sourcePath, destPath) {
       source = null;
       dest.close();
       dest = null;
-      fs5__default.default.copyFileSync(sourcePath, destPath);
+      fs6__default.default.copyFileSync(sourcePath, destPath);
     }
   } catch (error) {
     throw new DatabaseError(
@@ -5233,7 +5288,7 @@ async function copySqlite(sourcePath, destPath) {
 }
 function resolvePath(p) {
   if (p === ":memory:") return ":memory:";
-  return path5__default.default.isAbsolute(p) ? p : path5__default.default.resolve(process.cwd(), p);
+  return path7__default.default.isAbsolute(p) ? p : path7__default.default.resolve(process.cwd(), p);
 }
 
 // src/memory/index.ts
@@ -5360,6 +5415,723 @@ function adaptiveFetchK(topK, overFetchFactor, hasFilters) {
   return Math.min(Math.max(Math.ceil(topK * factor), topK), 1e3);
 }
 
+// src/graph/memory-node.ts
+function stubMemoryRecord(id) {
+  return {
+    id,
+    organization: "",
+    agent: "",
+    content: { text: "" },
+    metadata: {},
+    archived: false,
+    compressedInto: null,
+    createdAt: /* @__PURE__ */ new Date(0),
+    updatedAt: /* @__PURE__ */ new Date(0)
+  };
+}
+function serializeMetadata2(meta2) {
+  return JSON.stringify(meta2 ?? {});
+}
+function deserializeMetadata2(raw) {
+  if (raw == null || raw === "") return {};
+  if (typeof raw === "object" && !Array.isArray(raw)) {
+    return raw;
+  }
+  if (typeof raw !== "string") return {};
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch {
+  }
+  return {};
+}
+function rowToMemoryRecord(row) {
+  const id = String(row.id ?? row.n_id ?? "");
+  const createdAt = parseDate(row.created_at ?? row.createdAt);
+  const updatedAt = parseDate(row.updated_at ?? row.updatedAt);
+  return {
+    id,
+    organization: String(row.organization ?? ""),
+    agent: String(row.agent ?? ""),
+    content: { text: String(row.content_text ?? row.contentText ?? "") },
+    metadata: deserializeMetadata2(row.metadata_json ?? row.metadata),
+    archived: Boolean(row.archived),
+    compressedInto: row.compressed_into == null || row.compressed_into === "" ? null : String(row.compressed_into),
+    createdAt,
+    updatedAt
+  };
+}
+function parseDate(value) {
+  if (value instanceof Date) return value;
+  if (typeof value === "string" || typeof value === "number") {
+    const d = new Date(value);
+    if (!Number.isNaN(d.getTime())) return d;
+  }
+  return /* @__PURE__ */ new Date(0);
+}
+function entityIdFrom(name, type) {
+  const key = `${type.trim().toLowerCase()}::${name.trim().toLowerCase()}`;
+  let h = 2166136261;
+  for (let i = 0; i < key.length; i += 1) {
+    h ^= key.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  const a = (h >>> 0).toString(16).padStart(8, "0");
+  let h2 = 5381;
+  for (let i = 0; i < key.length; i += 1) {
+    h2 = h2 * 33 ^ key.charCodeAt(i);
+  }
+  const b = (h2 >>> 0).toString(16).padStart(8, "0");
+  return `ent_${a}${b}`;
+}
+
+// src/graph/sync/cascade.ts
+var ENTITY_MENTIONS_RELATION = "MENTIONS";
+function cascadeDeleteMemoryNode(db, memoryId) {
+  const node = db.prepare(
+    `SELECT id FROM graph_nodes WHERE type = 'memory' AND ref_id = ?`
+  ).get(memoryId);
+  if (!node) return;
+  db.prepare(
+    `DELETE FROM graph_edges WHERE from_node_id = ? OR to_node_id = ?`
+  ).run(node.id, node.id);
+  db.prepare(`DELETE FROM graph_nodes WHERE id = ?`).run(node.id);
+}
+
+// src/graph/providers/sqlite-graph.ts
+var DEFAULT_GET_RELATED_DEPTH = 1;
+var MAX_GET_RELATED_DEPTH = 16;
+var SqliteGraphProvider = class {
+  name = "sqlite";
+  dbPath;
+  concurrency;
+  db = null;
+  opened = false;
+  constructor(options) {
+    if (!options?.path || typeof options.path !== "string" || !options.path.trim()) {
+      throw new ConfigurationError("sqlite graph requires a non-empty path");
+    }
+    this.dbPath = path7__default.default.resolve(options.path.trim());
+    this.concurrency = resolveConcurrencyConfig(options.concurrency);
+  }
+  supportsFileSnapshot() {
+    return this.dbPath !== ":memory:";
+  }
+  getDataPath() {
+    return this.dbPath === ":memory:" ? null : this.dbPath;
+  }
+  async open() {
+    if (this.opened) return;
+    try {
+      if (this.dbPath !== ":memory:") {
+        fs6__default.default.mkdirSync(path7__default.default.dirname(this.dbPath), { recursive: true });
+      }
+      const db = new sqlite$1.DatabaseSync(this.dbPath);
+      db.exec("PRAGMA journal_mode = WAL;");
+      db.exec(`
+        PRAGMA synchronous = NORMAL;
+        PRAGMA foreign_keys = ON;
+        PRAGMA busy_timeout = ${this.concurrency.lockTimeoutMs};
+        PRAGMA temp_store = MEMORY;
+        PRAGMA cache_size = -8192;
+        PRAGMA wal_autocheckpoint = 1000;
+      `);
+      db.exec(CREATE_GRAPH_NODES_TABLE);
+      db.exec(CREATE_GRAPH_EDGES_TABLE);
+      for (const indexSql of CREATE_GRAPH_INDEXES) {
+        db.exec(indexSql);
+      }
+      this.db = db;
+      this.opened = true;
+    } catch (error) {
+      try {
+        this.db?.close();
+      } catch {
+      }
+      this.db = null;
+      this.opened = false;
+      throw new DatabaseError(
+        `Failed to open SQLite graph database: ${describe(error)}`,
+        { cause: error instanceof Error ? error : void 0 }
+      );
+    }
+  }
+  async close() {
+    if (!this.db) {
+      this.opened = false;
+      return;
+    }
+    try {
+      try {
+        this.db.exec("PRAGMA optimize;");
+      } catch {
+      }
+      this.db.close();
+    } catch (error) {
+      throw new DatabaseError(
+        `Failed to close SQLite graph database: ${describe(error)}`,
+        { cause: error instanceof Error ? error : void 0 }
+      );
+    } finally {
+      this.db = null;
+      this.opened = false;
+    }
+  }
+  async linkMemories(fromId, toId, relation, metadata) {
+    const db = this.requireDb();
+    await this.withTx(() => {
+      const fromNode = this.ensureMemoryNodeSync(db, fromId);
+      const toNode = this.ensureMemoryNodeSync(db, toId);
+      db.prepare(
+        `DELETE FROM graph_edges
+         WHERE from_node_id = ? AND to_node_id = ? AND relation = ?`
+      ).run(fromNode, toNode, relation);
+      db.prepare(
+        `INSERT INTO graph_edges (id, from_node_id, to_node_id, relation, metadata, created_at)
+         VALUES (?, ?, ?, ?, ?, ?)`
+      ).run(
+        crypto.randomUUID(),
+        fromNode,
+        toNode,
+        relation,
+        serializeMetadata2(metadata),
+        nowIso2()
+      );
+    });
+  }
+  async unlinkMemories(fromId, toId, relation) {
+    const db = this.requireDb();
+    await this.withTx(() => {
+      const fromNode = this.findMemoryNodeId(db, fromId);
+      const toNode = this.findMemoryNodeId(db, toId);
+      if (!fromNode || !toNode) return;
+      if (relation !== void 0) {
+        db.prepare(
+          `DELETE FROM graph_edges
+           WHERE from_node_id = ? AND to_node_id = ? AND relation = ?`
+        ).run(fromNode, toNode, relation);
+        return;
+      }
+      db.prepare(
+        `DELETE FROM graph_edges WHERE from_node_id = ? AND to_node_id = ?`
+      ).run(fromNode, toNode);
+    });
+  }
+  /**
+   * Bounded recursive CTE over `graph_edges`.
+   *
+   * Default depth: {@link DEFAULT_GET_RELATED_DEPTH} (1). Cap: 16.
+   * Only memory↔memory edges are walked (entity MENTIONS edges are excluded).
+   * Cycle-safe via path membership (`instr`) so A→B→C→A terminates.
+   *
+   * Returns stub {@link MemoryRecord}s (id + empty fields). The facade
+   * re-hydrates full rows via `toMemoryRecord` from storage when possible.
+   */
+  async getRelated(memoryId, options) {
+    const db = this.requireDb();
+    const depth = Math.max(
+      1,
+      Math.min(options?.depth ?? DEFAULT_GET_RELATED_DEPTH, MAX_GET_RELATED_DEPTH)
+    );
+    const direction = options?.direction ?? "both";
+    const relation = options?.relation ?? null;
+    const start = this.findMemoryNodeId(db, memoryId);
+    if (!start) return [];
+    const sql = buildGetRelatedSql(direction);
+    const rows = db.prepare(sql).all(start, start, depth, relation, relation);
+    const seen = /* @__PURE__ */ new Set();
+    const out = [];
+    for (const row of rows) {
+      if (row.ref_id === memoryId || seen.has(row.ref_id)) continue;
+      seen.add(row.ref_id);
+      out.push(stubMemoryRecord(row.ref_id));
+    }
+    return out;
+  }
+  async upsertEntity(entity) {
+    const id = entityIdFrom(entity.name, entity.type);
+    const db = this.requireDb();
+    const meta2 = serializeMetadata2({
+      ...entity.metadata ?? {},
+      entityType: entity.type
+    });
+    await this.withTx(() => {
+      const existing = db.prepare(
+        `SELECT id FROM graph_nodes WHERE type = 'entity' AND ref_id = ?`
+      ).get(id);
+      if (existing) {
+        db.prepare(
+          `UPDATE graph_nodes SET name = ?, metadata = ? WHERE id = ?`
+        ).run(entity.name, meta2, existing.id);
+      } else {
+        db.prepare(
+          `INSERT INTO graph_nodes (id, type, ref_id, name, metadata, created_at)
+           VALUES (?, 'entity', ?, ?, ?, ?)`
+        ).run(id, id, entity.name, meta2, nowIso2());
+      }
+    });
+    return id;
+  }
+  async linkEntityToMemory(entityId, memoryId, role) {
+    const db = this.requireDb();
+    await this.withTx(() => {
+      const entity = db.prepare(
+        `SELECT id FROM graph_nodes WHERE type = 'entity' AND ref_id = ?`
+      ).get(entityId);
+      if (!entity) {
+        throw new DatabaseError(`Entity not found: ${entityId}`, {
+          operation: "linkEntityToMemory"
+        });
+      }
+      const memoryNode = this.ensureMemoryNodeSync(db, memoryId);
+      db.prepare(
+        `DELETE FROM graph_edges
+         WHERE from_node_id = ? AND to_node_id = ? AND relation = ?`
+      ).run(entity.id, memoryNode, ENTITY_MENTIONS_RELATION);
+      db.prepare(
+        `INSERT INTO graph_edges (id, from_node_id, to_node_id, relation, metadata, created_at)
+         VALUES (?, ?, ?, ?, ?, ?)`
+      ).run(
+        crypto.randomUUID(),
+        entity.id,
+        memoryNode,
+        ENTITY_MENTIONS_RELATION,
+        serializeMetadata2({ role: role ?? "" }),
+        nowIso2()
+      );
+    });
+  }
+  async deleteMemory(memoryId) {
+    const db = this.requireDb();
+    await this.withTx(() => {
+      cascadeDeleteMemoryNode(db, memoryId);
+    });
+  }
+  /**
+   * Raw Cypher escape hatch — **not supported** on the SQLite graph provider.
+   * Use the typed methods, or open the underlying SQLite file yourself for raw SQL.
+   */
+  async query(_cypher, _params) {
+    throw new DatabaseError(
+      "raw Cypher queries are not supported by the SQLite graph provider \u2014 use the typed methods, or query the underlying SQLite tables directly via your own connection if you need raw access",
+      {
+        operation: "query",
+        suggestion: "Use linkMemories / getRelated / upsertEntity / linkEntityToMemory, or open the graph .db file with node:sqlite for ad-hoc SQL"
+      }
+    );
+  }
+  async health() {
+    try {
+      if (!this.opened || !this.db) {
+        return { ok: false, backend: "sqlite", details: { reason: "not open" } };
+      }
+      const nodeCount = Number(
+        this.db.prepare(`SELECT COUNT(*) AS c FROM graph_nodes`).get().c
+      );
+      const edgeCount = Number(
+        this.db.prepare(`SELECT COUNT(*) AS c FROM graph_edges`).get().c
+      );
+      return {
+        ok: true,
+        backend: "sqlite",
+        details: {
+          path: this.dbPath,
+          embedded: true,
+          nodeCount,
+          edgeCount,
+          exists: this.dbPath === ":memory:" || fs6__default.default.existsSync(this.dbPath)
+        }
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        backend: "sqlite",
+        details: {
+          path: this.dbPath,
+          error: error instanceof Error ? error.message : String(error)
+        }
+      };
+    }
+  }
+  async withTx(fn) {
+    const db = this.requireDb();
+    return withImmediateTransaction(db, this.concurrency, fn);
+  }
+  requireDb() {
+    if (!this.db || !this.opened) {
+      throw new DatabaseError("SQLite graph is not open", {
+        operation: "graph",
+        suggestion: "Call ready() / open() before graph operations"
+      });
+    }
+    return this.db;
+  }
+  findMemoryNodeId(db, memoryId) {
+    const row = db.prepare(
+      `SELECT id FROM graph_nodes WHERE type = 'memory' AND ref_id = ?`
+    ).get(memoryId);
+    return row?.id ?? null;
+  }
+  ensureMemoryNodeSync(db, memoryId) {
+    const existing = this.findMemoryNodeId(db, memoryId);
+    if (existing) return existing;
+    db.prepare(
+      `INSERT INTO graph_nodes (id, type, ref_id, name, metadata, created_at)
+       VALUES (?, 'memory', ?, NULL, '{}', ?)`
+    ).run(memoryId, memoryId, nowIso2());
+    return memoryId;
+  }
+};
+function buildGetRelatedSql(direction) {
+  const mentions = ENTITY_MENTIONS_RELATION;
+  if (direction === "out") {
+    return `
+      WITH RECURSIVE walk(node_id, depth, path) AS (
+        SELECT ? AS node_id, 0, '/' || ? || '/'
+        UNION ALL
+        SELECT e.to_node_id, w.depth + 1, w.path || e.to_node_id || '/'
+        FROM walk w
+        JOIN graph_edges e ON e.from_node_id = w.node_id
+        JOIN graph_nodes dest ON dest.id = e.to_node_id AND dest.type = 'memory'
+        WHERE w.depth < ?
+          AND instr(w.path, '/' || e.to_node_id || '/') = 0
+          AND (? IS NULL OR e.relation = ?)
+          AND e.relation != '${mentions}'
+      )
+      SELECT DISTINCT n.ref_id AS ref_id
+      FROM walk w
+      JOIN graph_nodes n ON n.id = w.node_id
+      WHERE w.depth > 0 AND n.type = 'memory'
+    `;
+  }
+  if (direction === "in") {
+    return `
+      WITH RECURSIVE walk(node_id, depth, path) AS (
+        SELECT ? AS node_id, 0, '/' || ? || '/'
+        UNION ALL
+        SELECT e.from_node_id, w.depth + 1, w.path || e.from_node_id || '/'
+        FROM walk w
+        JOIN graph_edges e ON e.to_node_id = w.node_id
+        JOIN graph_nodes src ON src.id = e.from_node_id AND src.type = 'memory'
+        WHERE w.depth < ?
+          AND instr(w.path, '/' || e.from_node_id || '/') = 0
+          AND (? IS NULL OR e.relation = ?)
+          AND e.relation != '${mentions}'
+      )
+      SELECT DISTINCT n.ref_id AS ref_id
+      FROM walk w
+      JOIN graph_nodes n ON n.id = w.node_id
+      WHERE w.depth > 0 AND n.type = 'memory'
+    `;
+  }
+  return `
+    WITH RECURSIVE walk(node_id, depth, path) AS (
+      SELECT ? AS node_id, 0, '/' || ? || '/'
+      UNION ALL
+      SELECT neighbor.id, w.depth + 1, w.path || neighbor.id || '/'
+      FROM walk w
+      JOIN graph_edges e
+        ON e.from_node_id = w.node_id OR e.to_node_id = w.node_id
+      JOIN graph_nodes neighbor
+        ON neighbor.id = CASE
+             WHEN e.from_node_id = w.node_id THEN e.to_node_id
+             ELSE e.from_node_id
+           END
+        AND neighbor.type = 'memory'
+      WHERE w.depth < ?
+        AND instr(w.path, '/' || neighbor.id || '/') = 0
+        AND (? IS NULL OR e.relation = ?)
+        AND e.relation != '${mentions}'
+    )
+    SELECT DISTINCT n.ref_id AS ref_id
+    FROM walk w
+    JOIN graph_nodes n ON n.id = w.node_id
+    WHERE w.depth > 0 AND n.type = 'memory'
+  `;
+}
+function nowIso2() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function describe(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/graph/providers/neo4j.ts
+var Neo4jGraphProvider = class {
+  name = "neo4j";
+  url;
+  username;
+  password;
+  database;
+  driver = null;
+  opened = false;
+  constructor(options) {
+    if (!options?.url?.trim()) {
+      throw new ConfigurationError("neo4j graph requires a non-empty url");
+    }
+    if (!options?.username?.trim()) {
+      throw new ConfigurationError("neo4j graph requires a non-empty username");
+    }
+    if (typeof options.password !== "string") {
+      throw new ConfigurationError("neo4j graph requires a password string");
+    }
+    this.url = options.url.trim();
+    this.username = options.username.trim();
+    this.password = options.password;
+    this.database = options.database?.trim() || void 0;
+  }
+  supportsFileSnapshot() {
+    return false;
+  }
+  getDataPath() {
+    return null;
+  }
+  async open() {
+    if (this.opened) return;
+    let mod;
+    try {
+      mod = await import('neo4j-driver');
+    } catch {
+      throw new ConfigurationError(
+        'Neo4j graph requires the optional "neo4j-driver" package. Install it with: npm install neo4j-driver'
+      );
+    }
+    this.driver = mod.driver(
+      this.url,
+      mod.auth.basic(this.username, this.password)
+    );
+    await this.driver.verifyConnectivity();
+    this.opened = true;
+    await this.withSession(async (session) => {
+      try {
+        await session.run(
+          `CREATE CONSTRAINT memory_id IF NOT EXISTS FOR (m:Memory) REQUIRE m.id IS UNIQUE`
+        );
+      } catch {
+      }
+      try {
+        await session.run(
+          `CREATE CONSTRAINT entity_id IF NOT EXISTS FOR (e:Entity) REQUIRE e.id IS UNIQUE`
+        );
+      } catch {
+      }
+    });
+  }
+  async close() {
+    if (this.driver) {
+      await this.driver.close();
+    }
+    this.driver = null;
+    this.opened = false;
+  }
+  requireDriver() {
+    if (!this.driver || !this.opened) {
+      throw new DatabaseError("Neo4j graph is not open", {
+        operation: "graph",
+        suggestion: "Call ready() / open() before graph operations"
+      });
+    }
+    return this.driver;
+  }
+  async withSession(fn) {
+    const driver = this.requireDriver();
+    const session = this.database ? driver.session({ database: this.database }) : driver.session();
+    try {
+      return await fn(session);
+    } finally {
+      await session.close();
+    }
+  }
+  async run(cypher, params = {}) {
+    return this.withSession(async (session) => {
+      const result = await session.run(cypher, params);
+      return result.records.map((rec) => {
+        try {
+          return rec.toObject();
+        } catch {
+          const obj = {};
+          for (const key of rec.keys) {
+            obj[key] = unwrapNeo4jValue(rec.get(key));
+          }
+          return obj;
+        }
+      });
+    });
+  }
+  async ensureMemoryNode(id) {
+    await this.run(
+      `MERGE (m:Memory { id: $id })
+       ON CREATE SET
+         m.organization = '',
+         m.agent = '',
+         m.content_text = '',
+         m.metadata_json = '{}',
+         m.archived = false,
+         m.compressed_into = '',
+         m.created_at = '',
+         m.updated_at = ''`,
+      { id }
+    );
+  }
+  async linkMemories(fromId, toId, relation, metadata) {
+    await this.ensureMemoryNode(fromId);
+    await this.ensureMemoryNode(toId);
+    await this.run(
+      `MATCH (a:Memory { id: $fromId }), (b:Memory { id: $toId })
+       MERGE (a)-[r:RELATED { relation: $relation }]->(b)
+       SET r.metadata_json = $metadata`,
+      {
+        fromId,
+        toId,
+        relation,
+        metadata: serializeMetadata2(metadata)
+      }
+    );
+  }
+  async unlinkMemories(fromId, toId, relation) {
+    if (relation !== void 0) {
+      await this.run(
+        `MATCH (a:Memory { id: $fromId })-[r:RELATED { relation: $relation }]->(b:Memory { id: $toId })
+         DELETE r`,
+        { fromId, toId, relation }
+      );
+      return;
+    }
+    await this.run(
+      `MATCH (a:Memory { id: $fromId })-[r:RELATED]->(b:Memory { id: $toId })
+       DELETE r`,
+      { fromId, toId }
+    );
+  }
+  /**
+   * Native Neo4j variable-length path traversal.
+   * Relationship filter uses RELATED.relation property for parity with Kuzu.
+   */
+  async getRelated(memoryId, options) {
+    const depth = Math.max(1, Math.min(options?.depth ?? 1, 16));
+    const direction = options?.direction ?? "both";
+    const relation = options?.relation;
+    const pathPattern = direction === "out" ? `(start)-[:RELATED*1..${depth}]->(n:Memory)` : direction === "in" ? `(start)<-[:RELATED*1..${depth}]-(n:Memory)` : `(start)-[:RELATED*1..${depth}]-(n:Memory)`;
+    const cypher = relation ? `MATCH (start:Memory { id: $id }), p = ${pathPattern}
+         WHERE ALL(r IN relationships(p) WHERE r.relation = $relation)
+           AND n.id <> $id
+         RETURN DISTINCT
+           n.id AS id, n.organization AS organization, n.agent AS agent,
+           n.content_text AS content_text, n.metadata_json AS metadata_json,
+           n.archived AS archived, n.compressed_into AS compressed_into,
+           n.created_at AS created_at, n.updated_at AS updated_at` : `MATCH (start:Memory { id: $id }), p = ${pathPattern}
+         WHERE n.id <> $id
+         RETURN DISTINCT
+           n.id AS id, n.organization AS organization, n.agent AS agent,
+           n.content_text AS content_text, n.metadata_json AS metadata_json,
+           n.archived AS archived, n.compressed_into AS compressed_into,
+           n.created_at AS created_at, n.updated_at AS updated_at`;
+    const params = { id: memoryId };
+    if (relation !== void 0) params.relation = relation;
+    const rows = await this.run(cypher, params);
+    return rows.map(
+      (row) => rowToMemoryRecord(unwrapRow(row))
+    );
+  }
+  async upsertEntity(entity) {
+    const id = entityIdFrom(entity.name, entity.type);
+    await this.run(
+      `MERGE (e:Entity { id: $id })
+       SET e.name = $name, e.type = $type, e.metadata_json = $metadata`,
+      {
+        id,
+        name: entity.name,
+        type: entity.type,
+        metadata: serializeMetadata2(entity.metadata)
+      }
+    );
+    return id;
+  }
+  async linkEntityToMemory(entityId, memoryId, role) {
+    await this.ensureMemoryNode(memoryId);
+    const found = await this.run(
+      `MATCH (e:Entity { id: $id }) RETURN e.id AS id`,
+      { id: entityId }
+    );
+    if (found.length === 0) {
+      throw new DatabaseError(`Entity not found: ${entityId}`, {
+        operation: "linkEntityToMemory"
+      });
+    }
+    await this.run(
+      `MATCH (e:Entity { id: $entityId }), (m:Memory { id: $memoryId })
+       MERGE (e)-[r:MENTIONS]->(m)
+       SET r.role = $role`,
+      { entityId, memoryId, role: role ?? "" }
+    );
+  }
+  async deleteMemory(memoryId) {
+    await this.run(
+      `MATCH (m:Memory { id: $id })
+       DETACH DELETE m`,
+      { id: memoryId }
+    );
+  }
+  async query(cypher, params) {
+    return this.run(cypher, params ?? {});
+  }
+  async health() {
+    try {
+      if (!this.opened || !this.driver) {
+        return { ok: false, backend: "neo4j", details: { reason: "not open" } };
+      }
+      await this.driver.verifyConnectivity();
+      let serverInfo = void 0;
+      if (typeof this.driver.getServerInfo === "function") {
+        serverInfo = await this.driver.getServerInfo();
+      }
+      return {
+        ok: true,
+        backend: "neo4j",
+        details: {
+          url: this.url,
+          database: this.database ?? "default",
+          networked: true,
+          serverInfo
+        }
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        backend: "neo4j",
+        details: {
+          url: this.url,
+          error: error instanceof Error ? error.message : String(error)
+        }
+      };
+    }
+  }
+};
+function unwrapNeo4jValue(value) {
+  if (value == null) return value;
+  if (typeof value === "object" && value !== null && "toNumber" in value) {
+    try {
+      return value.toNumber();
+    } catch {
+    }
+  }
+  if (typeof value === "object" && value !== null && "properties" in value) {
+    return unwrapRow(
+      value.properties
+    );
+  }
+  return value;
+}
+function unwrapRow(row) {
+  const out = {};
+  for (const [k, v] of Object.entries(row)) {
+    out[k] = unwrapNeo4jValue(v);
+  }
+  return out;
+}
+
 // src/core/validate.ts
 function assertNonEmpty(value, fieldName) {
   if (typeof value !== "string" || value.trim().length === 0) {
@@ -5440,9 +6212,21 @@ function validateTelemetryConfig(config) {
   if (!config.database || typeof config.database !== "object") {
     throw new ConfigurationError("telemetry.database is required when telemetry is enabled");
   }
+  const providerName = String(
+    config.database.provider ?? ""
+  );
+  if (providerName === "kuzu" || providerName === "neo4j") {
+    throw new ConfigurationError(
+      `telemetry supports sqlite or postgres only (got "${providerName}")`,
+      {
+        reason: `provider=${providerName}`,
+        suggestion: 'Use telemetry: { database: { provider: "sqlite", url: "./telemetry.db" } }. Graph backends (kuzu/neo4j) are not valid telemetry stores.'
+      }
+    );
+  }
   if (config.database.provider !== "sqlite") {
     throw new ConfigurationError(
-      `Unsupported telemetry provider "${config.database.provider}". Only "sqlite" is implemented in v0.3.0; PostgreSQL will be added later without changing application code.`,
+      `Unsupported telemetry provider "${config.database.provider}". Only "sqlite" is implemented; PostgreSQL typed but not implemented. Telemetry supports sqlite or postgres only \u2014 not kuzu/neo4j.`,
       {
         reason: `provider=${config.database.provider}`,
         suggestion: 'Use telemetry: { database: { provider: "sqlite", url: "./telemetry.db" } }'
@@ -5527,14 +6311,74 @@ function validateWolbargOptions(options) {
   if (telemetry && !isTelemetryProvider(telemetry)) {
     telemetry = validateTelemetryConfig(telemetry);
   }
+  let graph = options.graph;
+  if (graph !== void 0) {
+    graph = resolveGraphInput(graph);
+  }
   return {
     ...options,
     organization: options.organization.trim(),
     storage,
     database: void 0,
-    ...telemetry ? { telemetry } : {}
+    ...telemetry ? { telemetry } : {},
+    ...graph !== void 0 ? { graph } : {}
   };
 }
+function resolveGraphInput(input) {
+  if (input == null || typeof input !== "object") {
+    throw new ConfigurationError(
+      "graph must be a GraphProvider instance or a config object",
+      {
+        suggestion: "Use graph: sqliteGraph({ path }) or graph: neo4jGraph({ url, username, password })"
+      }
+    );
+  }
+  if (Array.isArray(input)) {
+    throw new ConfigurationError(
+      "graph must be a GraphProvider instance or a config object",
+      {
+        suggestion: "Use graph: sqliteGraph({ path }) or graph: neo4jGraph({ url, username, password })"
+      }
+    );
+  }
+  if (isGraphProvider(input)) {
+    return input;
+  }
+  const config = input;
+  if (config.provider === "sqlite") {
+    if (typeof config.path !== "string" || !config.path.trim()) {
+      throw new ConfigurationError(
+        'graph sqlite config requires a non-empty "path"'
+      );
+    }
+    return new SqliteGraphProvider({ path: config.path });
+  }
+  if (config.provider === "neo4j") {
+    if (typeof config.url !== "string" || !config.url.trim()) {
+      throw new ConfigurationError('graph neo4j config requires a non-empty "url"');
+    }
+    if (typeof config.username !== "string" || !config.username.trim()) {
+      throw new ConfigurationError(
+        'graph neo4j config requires a non-empty "username"'
+      );
+    }
+    if (typeof config.password !== "string") {
+      throw new ConfigurationError('graph neo4j config requires a "password" string');
+    }
+    return new Neo4jGraphProvider({
+      url: config.url,
+      username: config.username,
+      password: config.password,
+      database: config.database
+    });
+  }
+  throw new ConfigurationError(
+    `Unsupported graph provider "${String(config.provider)}". Supported: "sqlite", "neo4j", or a GraphProvider instance.`,
+    {
+      suggestion: 'Use graph: sqliteGraph({ path: "./local-graph.db" }) or graph: neo4jGraph({ url, username, password })'
+    }
+  );
+}
 
 // src/telemetry/logger.ts
 var LEVEL_ORDER = {
@@ -5814,7 +6658,7 @@ var SqliteEventDatabase = class {
     try {
       const dbPath = this.resolvePath(this.url);
       if (dbPath !== ":memory:" && !this.readonly) {
-        fs5__default.default.mkdirSync(path5__default.default.dirname(dbPath), { recursive: true });
+        fs6__default.default.mkdirSync(path7__default.default.dirname(dbPath), { recursive: true });
       }
       const db = new sqlite$1.DatabaseSync(dbPath, {
         allowExtension: false,
@@ -5859,7 +6703,7 @@ var SqliteEventDatabase = class {
       this.db = null;
       this.columns.clear();
       throw new InitializationError(
-        `Failed to open telemetry EventDatabase: ${describe(error)}`,
+        `Failed to open telemetry EventDatabase: ${describe2(error)}`,
         { cause: error instanceof Error ? error : void 0 }
       );
     }
@@ -5914,7 +6758,7 @@ var SqliteEventDatabase = class {
       return event;
     } catch (error) {
       throw new DatabaseError(
-        `Failed to write telemetry event: ${describe(error)}`,
+        `Failed to write telemetry event: ${describe2(error)}`,
         { cause: error instanceof Error ? error : void 0 }
       );
     }
@@ -6070,7 +6914,7 @@ var SqliteEventDatabase = class {
   }
   resolvePath(url) {
     if (url === ":memory:") return ":memory:";
-    return path5__default.default.isAbsolute(url) ? url : path5__default.default.resolve(process.cwd(), url);
+    return path7__default.default.isAbsolute(url) ? url : path7__default.default.resolve(process.cwd(), url);
   }
 };
 function normalizeEvent(input) {
@@ -6155,7 +6999,7 @@ function parseJson(value) {
     return null;
   }
 }
-function describe(error) {
+function describe2(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
@@ -6233,16 +7077,15 @@ var SqliteTelemetryProvider = class {
     }
   }
 };
-var SDK_VERSION2 = "0.3.0";
 var SqliteCheckpointProvider = class {
   name = "sqlite";
   directory;
   ready = false;
   constructor(options) {
-    this.directory = options?.directory ?? path5__default.default.resolve(process.cwd(), ".wolbarg", "checkpoints");
+    this.directory = options?.directory ?? path7__default.default.resolve(process.cwd(), ".wolbarg", "checkpoints");
   }
   async open() {
-    fs5__default.default.mkdirSync(this.directory, { recursive: true });
+    fs6__default.default.mkdirSync(this.directory, { recursive: true });
     this.ready = true;
   }
   async close() {
@@ -6252,7 +7095,7 @@ var SqliteCheckpointProvider = class {
     this.requireReady();
     assertCheckpointName(name);
     const metaPath = this.metaPath(name);
-    if (fs5__default.default.existsSync(metaPath)) {
+    if (fs6__default.default.existsSync(metaPath)) {
       throw new ValidationError(
         `Checkpoint "${name}" already exists. Choose a different name \u2014 checkpoints are never overwritten.`
       );
@@ -6263,7 +7106,7 @@ var SqliteCheckpointProvider = class {
         "Cannot checkpoint an in-memory database. Use a file-backed SQLite database."
       );
     }
-    if (!fs5__default.default.existsSync(resolvedSource)) {
+    if (!fs6__default.default.existsSync(resolvedSource)) {
       throw new DatabaseError(
         `Failed to execute checkpoint()
 Reason:
@@ -6274,18 +7117,18 @@ Ensure Wolbarg has been initialized and the database path is correct.`
     }
     const snapshotPath = this.snapshotPath(name);
     await safeSqliteBackup(resolvedSource, snapshotPath);
-    const stats = fs5__default.default.statSync(snapshotPath);
+    const stats = fs6__default.default.statSync(snapshotPath);
     const meta2 = {
       name,
       description: options?.description ?? null,
       createdAt: nowIso(),
-      sdkVersion: SDK_VERSION2,
+      sdkVersion: SDK_VERSION,
       provider: this.name,
       snapshotPath,
       sourcePath: resolvedSource,
       sizeBytes: stats.size
     };
-    fs5__default.default.writeFileSync(metaPath, JSON.stringify(meta2, null, 2), "utf8");
+    fs6__default.default.writeFileSync(metaPath, JSON.stringify(meta2, null, 2), "utf8");
     return meta2;
   }
   async rollback(name, targetPath) {
@@ -6300,11 +7143,11 @@ Ensure Wolbarg has been initialized and the database path is correct.`
         "Cannot rollback into an in-memory database."
       );
     }
-    fs5__default.default.mkdirSync(path5__default.default.dirname(resolvedTarget), { recursive: true });
+    fs6__default.default.mkdirSync(path7__default.default.dirname(resolvedTarget), { recursive: true });
     for (const suffix of ["", "-wal", "-shm"]) {
       const side = `${resolvedTarget}${suffix}`;
-      if (fs5__default.default.existsSync(side)) {
-        fs5__default.default.rmSync(side, { force: true });
+      if (fs6__default.default.existsSync(side)) {
+        fs6__default.default.rmSync(side, { force: true });
       }
     }
     await safeSqliteBackup(meta2.snapshotPath, resolvedTarget);
@@ -6315,26 +7158,26 @@ Ensure Wolbarg has been initialized and the database path is correct.`
     const metaPath = this.metaPath(name);
     const snapshotPath = this.snapshotPath(name);
     let removed = false;
-    if (fs5__default.default.existsSync(metaPath)) {
-      fs5__default.default.rmSync(metaPath, { force: true });
+    if (fs6__default.default.existsSync(metaPath)) {
+      fs6__default.default.rmSync(metaPath, { force: true });
       removed = true;
     }
-    if (fs5__default.default.existsSync(snapshotPath)) {
-      fs5__default.default.rmSync(snapshotPath, { force: true });
+    if (fs6__default.default.existsSync(snapshotPath)) {
+      fs6__default.default.rmSync(snapshotPath, { force: true });
       removed = true;
     }
     return removed;
   }
   async listCheckpoints() {
     this.requireReady();
-    if (!fs5__default.default.existsSync(this.directory)) {
+    if (!fs6__default.default.existsSync(this.directory)) {
       return [];
     }
-    const files = fs5__default.default.readdirSync(this.directory).filter((f) => f.endsWith(".json"));
+    const files = fs6__default.default.readdirSync(this.directory).filter((f) => f.endsWith(".json"));
     const out = [];
     for (const file of files) {
       try {
-        const raw = fs5__default.default.readFileSync(path5__default.default.join(this.directory, file), "utf8");
+        const raw = fs6__default.default.readFileSync(path7__default.default.join(this.directory, file), "utf8");
         out.push(JSON.parse(raw));
       } catch {
       }
@@ -6344,20 +7187,81 @@ Ensure Wolbarg has been initialized and the database path is correct.`
   async getCheckpoint(name) {
     this.requireReady();
     const metaPath = this.metaPath(name);
-    if (!fs5__default.default.existsSync(metaPath)) {
+    if (!fs6__default.default.existsSync(metaPath)) {
       return null;
     }
     try {
-      return JSON.parse(fs5__default.default.readFileSync(metaPath, "utf8"));
+      return JSON.parse(fs6__default.default.readFileSync(metaPath, "utf8"));
     } catch {
       return null;
     }
   }
+  /**
+   * Consistent SQLite file backup (WAL checkpoint + backup API / copy).
+   * Used for memory snapshots and for secondary files such as the graph DB.
+   */
+  async backupSqliteFile(sourcePath, destPath) {
+    this.requireReady();
+    const resolved = resolveDbPath(sourcePath);
+    if (resolved === ":memory:") {
+      throw new ConfigurationError(
+        "Cannot backup an in-memory database. Use a file-backed SQLite database."
+      );
+    }
+    if (!fs6__default.default.existsSync(resolved)) {
+      throw new DatabaseError(
+        `SQLite file not found at ${resolved}`,
+        {
+          suggestion: "Ensure the source database exists before backing up."
+        }
+      );
+    }
+    await safeSqliteBackup(resolved, destPath);
+  }
+  /**
+   * Snapshot a secondary SQLite file (typically the graph DB) next to a named
+   * memory checkpoint as `{name}.graph.db`.
+   */
+  async checkpointGraph(name, graphSourcePath) {
+    this.requireReady();
+    assertCheckpointName(name);
+    const dest = this.graphSnapshotPath(name);
+    await this.backupSqliteFile(graphSourcePath, dest);
+    return dest;
+  }
+  /**
+   * Restore a previously snapshotted graph SQLite file into `targetPath`.
+   */
+  async rollbackGraph(name, targetPath) {
+    this.requireReady();
+    const snapshot = this.graphSnapshotPath(name);
+    if (!fs6__default.default.existsSync(snapshot)) {
+      return;
+    }
+    const resolvedTarget = resolveDbPath(targetPath);
+    if (resolvedTarget === ":memory:") {
+      throw new ConfigurationError(
+        "Cannot rollback graph into an in-memory database."
+      );
+    }
+    fs6__default.default.mkdirSync(path7__default.default.dirname(resolvedTarget), { recursive: true });
+    for (const suffix of ["", "-wal", "-shm"]) {
+      const side = `${resolvedTarget}${suffix}`;
+      if (fs6__default.default.existsSync(side)) {
+        fs6__default.default.rmSync(side, { force: true });
+      }
+    }
+    await safeSqliteBackup(snapshot, resolvedTarget);
+  }
+  /** Absolute path of the graph snapshot for a named checkpoint, if present. */
+  graphSnapshotPath(name) {
+    return path7__default.default.join(this.directory, `${sanitize(name)}.graph.db`);
+  }
   metaPath(name) {
-    return path5__default.default.join(this.directory, `${sanitize(name)}.json`);
+    return path7__default.default.join(this.directory, `${sanitize(name)}.json`);
   }
   snapshotPath(name) {
-    return path5__default.default.join(this.directory, `${sanitize(name)}.db`);
+    return path7__default.default.join(this.directory, `${sanitize(name)}.db`);
   }
   requireReady() {
     if (!this.ready) {
@@ -6380,12 +7284,12 @@ function assertCheckpointName(name) {
 }
 function resolveDbPath(connectionString) {
   if (connectionString === ":memory:") return ":memory:";
-  return path5__default.default.isAbsolute(connectionString) ? connectionString : path5__default.default.resolve(process.cwd(), connectionString);
+  return path7__default.default.isAbsolute(connectionString) ? connectionString : path7__default.default.resolve(process.cwd(), connectionString);
 }
 async function safeSqliteBackup(sourcePath, destPath) {
-  fs5__default.default.mkdirSync(path5__default.default.dirname(destPath), { recursive: true });
-  if (fs5__default.default.existsSync(destPath)) {
-    fs5__default.default.rmSync(destPath, { force: true });
+  fs6__default.default.mkdirSync(path7__default.default.dirname(destPath), { recursive: true });
+  if (fs6__default.default.existsSync(destPath)) {
+    fs6__default.default.rmSync(destPath, { force: true });
   }
   let source = null;
   let dest = null;
@@ -6404,7 +7308,7 @@ async function safeSqliteBackup(sourcePath, destPath) {
       source = null;
       dest.close();
       dest = null;
-      fs5__default.default.copyFileSync(sourcePath, destPath);
+      fs6__default.default.copyFileSync(sourcePath, destPath);
     }
   } catch (error) {
     throw new DatabaseError(
@@ -6500,6 +7404,7 @@ var Wolbarg = class {
   keywordSearch = null;
   ocr = null;
   vision = null;
+  graph = null;
   chunking = null;
   retrievalConfig = {};
   embeddingDimensions = null;
@@ -6546,6 +7451,9 @@ var Wolbarg = class {
     this.keywordSearch = validated.keywordSearch ?? null;
     this.ocr = validated.ocr ?? null;
     this.vision = validated.vision ?? null;
+    if (validated.graph) {
+      this.graph = validated.graph;
+    }
     this.chunking = validated.chunking ?? null;
     this.retrievalConfig = validated.retrieval ?? {};
     this.subscribeBackend = new SqliteSubscribeEmitter();
@@ -6624,6 +7532,7 @@ var Wolbarg = class {
       await this.storage.open();
       await this.telemetry.open();
       await this.checkpointProvider?.open();
+      await this.graph?.open();
       if (this.rawEmbedding && this.embeddingCacheConfig.enabled) {
         if (this.storage instanceof SqliteStorageProvider) {
           const sqlite2 = this.storage;
@@ -6675,6 +7584,7 @@ var Wolbarg = class {
       this.initialized = true;
       this.telemetry.emitStartup(this.storage.name);
     } catch (error) {
+      await this.graph?.close().catch(() => void 0);
       await this.storage.close().catch(() => void 0);
       await this.telemetry.close().catch(() => void 0);
       this.initialized = false;
@@ -6701,7 +7611,7 @@ var Wolbarg = class {
         metadata: result.metadata,
         agentId: result.agent,
         tags: telemetryTags(result.metadata),
-        extra: { upsertAction: result.action }
+        extra: { upsertAction: result.action, action: result.action }
       });
       return result;
     } catch (error) {
@@ -7405,6 +8315,13 @@ var Wolbarg = class {
         tags: commonTags(serialized.map((result) => result.metadata))
       };
       if (!explain) {
+        if (options.includeGraph === true && this.graph) {
+          const tGraph = performance.now();
+          for (const hit of serialized) {
+            hit.related = await this.hydrateRelated(hit.id);
+          }
+          trace.mark("databaseReadMs", performance.now() - tGraph);
+        }
         trace.success(telemetryFields);
         return serialized;
       }
@@ -7757,21 +8674,82 @@ var Wolbarg = class {
       throw wrapOperationError("ingest", error);
     }
   }
+  /**
+   * Link two memories in the optional graph layer.
+   * Throws {@link ProviderNotConfiguredError} when no graph provider is set.
+   */
+  async linkMemories(fromId, toId, relation, metadata) {
+    const trace = this.telemetry.start("linkMemories");
+    try {
+      await this.requireReady();
+      const graph = this.requireGraph("linkMemories");
+      assertNonEmptyString(fromId, "fromId");
+      assertNonEmptyString(toId, "toId");
+      assertNonEmptyString(relation, "relation");
+      const tGraph = performance.now();
+      await graph.linkMemories(
+        fromId.trim(),
+        toId.trim(),
+        relation.trim(),
+        metadata
+      );
+      trace.mark("databaseWriteMs", performance.now() - tGraph);
+      trace.success({
+        provider: graph.name,
+        memoryIds: [fromId.trim(), toId.trim()],
+        extra: { relation: relation.trim() }
+      });
+    } catch (error) {
+      trace.failure(error);
+      throw wrapOperationError("linkMemories", error);
+    }
+  }
+  /**
+   * Traverse related memories via the optional graph layer.
+   * Throws {@link ProviderNotConfiguredError} when no graph provider is set.
+   * Results are re-hydrated from SQL storage when available.
+   */
+  async getRelated(memoryId, options) {
+    const trace = this.telemetry.start("getRelated");
+    try {
+      await this.requireReady();
+      const graph = this.requireGraph("getRelated");
+      assertNonEmptyString(memoryId, "memoryId");
+      const tGraph = performance.now();
+      const related = await this.hydrateRelated(memoryId.trim(), options);
+      trace.mark("databaseReadMs", performance.now() - tGraph);
+      trace.success({
+        provider: graph.name,
+        memoryIds: [memoryId.trim(), ...related.map((r) => r.id)],
+        returnedCount: related.length
+      });
+      return related;
+    } catch (error) {
+      trace.failure(error);
+      throw wrapOperationError("getRelated", error);
+    }
+  }
   async forget(options) {
     const trace = this.telemetry.start("forget");
     try {
       const { storage, organization } = await this.requireReady();
+      const deletedIds = [];
       const deleted = await this.withWriteLock(async () => {
         if ("id" in options && options.id !== void 0) {
           assertNonEmptyString(options.id, "id");
-          const ok = await storage.deleteMemoryById(
-            options.id.trim(),
-            organization
-          );
+          const id = options.id.trim();
+          const ok = await storage.deleteMemoryById(id, organization);
+          if (ok) deletedIds.push(id);
           return ok ? 1 : 0;
         }
         if ("filter" in options && options.filter?.agent) {
           assertNonEmptyString(options.filter.agent, "filter.agent");
+          const rows = await storage.listMemories({
+            organization,
+            agent: options.filter.agent.trim(),
+            includeArchived: true
+          });
+          for (const row of rows) deletedIds.push(row.id);
           return storage.deleteMemoriesByFilter({
             organization,
             agent: options.filter.agent.trim(),
@@ -7782,12 +8760,20 @@ var Wolbarg = class {
           "forget requires either { id } or { filter: { agent } }"
         );
       });
+      if (deleted > 0 && this.graph && deletedIds.length > 0) {
+        const tGraph = performance.now();
+        for (const id of deletedIds) {
+          await this.graph.deleteMemory(id);
+        }
+        trace.mark("databaseWriteMs", performance.now() - tGraph);
+      }
       trace.success({
         provider: storage.name,
         returnedCount: deleted,
-        memoryIds: "id" in options && options.id ? [options.id.trim()] : null,
+        memoryIds: deletedIds.length > 0 ? deletedIds : null,
         filters: "filter" in options ? options.filter : null,
-        agentId: "filter" in options ? options.filter?.agent?.trim() ?? null : null
+        agentId: "filter" in options ? options.filter?.agent?.trim() ?? null : null,
+        extra: this.graph ? { graphCascade: deletedIds.length } : void 0
       });
       if (deleted > 0) {
         this.emitChange({
@@ -7871,6 +8857,15 @@ var Wolbarg = class {
         );
       }
       const deleted = await this.withWriteLock(async () => {
+        if (this.graph) {
+          const rows = await storage.listMemories({
+            organization,
+            includeArchived: true
+          });
+          for (const row of rows) {
+            await this.graph.deleteMemory(row.id);
+          }
+        }
         return storage.clearOrganization(organization);
       });
       trace.success({ provider: storage.name, returnedCount: deleted });
@@ -7887,8 +8882,10 @@ var Wolbarg = class {
       await this.requireReady();
       const provider = this.requireCheckpointProvider();
       const source = this.requireMemoryDbPath();
+      this.assertGraphCheckpointSupported("checkpoint");
       const tCheckpoint = performance.now();
       const meta2 = await provider.checkpoint(name, source, options);
+      await this.snapshotGraphAlongside(meta2.snapshotPath, "checkpoint");
       trace.mark("databaseWriteMs", performance.now() - tCheckpoint);
       trace.success({
         provider: provider.name,
@@ -7917,8 +8914,13 @@ var Wolbarg = class {
         await this.storage.close();
         storageClosed = true;
       }
+      const graphClosed = await this.closeGraphForSnapshot();
       const tRollback = performance.now();
       const meta2 = await provider.rollback(name, target);
+      await this.restoreGraphAlongside(meta2.snapshotPath, "rollback");
+      if (graphClosed) {
+        await this.graph?.open();
+      }
       trace.mark("databaseWriteMs", performance.now() - tRollback);
       await this.storage?.open();
       storageClosed = false;
@@ -8004,6 +9006,7 @@ var Wolbarg = class {
     try {
       await this.requireReady();
       const source = this.requireMemoryDbPath();
+      this.assertGraphCheckpointSupported("export");
       if (this.storage?.name === "sqlite") {
       }
       const result = await this.transfer.exportTo(
@@ -8011,6 +9014,7 @@ var Wolbarg = class {
         source,
         this.organization ?? void 0
       );
+      await this.snapshotGraphAlongside(result.path, "export");
       trace.success({
         provider: "sqlite",
         extra: { path: result.path, sizeBytes: result.sizeBytes }
@@ -8036,10 +9040,16 @@ var Wolbarg = class {
         await this.storage.close();
         storageClosed = true;
       }
+      const graphClosed = await this.closeGraphForSnapshot();
+      this.assertGraphCheckpointSupported("import");
       const result = await this.transfer.importFrom(
         exportPath,
         target
       );
+      await this.restoreGraphAlongside(result.path, "import");
+      if (graphClosed) {
+        await this.graph?.open();
+      }
       await this.storage?.open();
       storageClosed = false;
       if (this.embeddingDimensions !== null) {
@@ -8093,6 +9103,8 @@ var Wolbarg = class {
     this.pgListenBackend = null;
     await this.telemetry.close().catch(() => void 0);
     await this.checkpointProvider?.close().catch(() => void 0);
+    await this.graph?.close().catch(() => void 0);
+    this.graph = null;
     if (this.storage) {
       await this.storage.close();
     }
@@ -8138,6 +9150,106 @@ var Wolbarg = class {
     }
     return this.checkpointProvider;
   }
+  requireGraph(method) {
+    if (!this.graph) {
+      throw new ProviderNotConfiguredError(
+        "graph",
+        method,
+        "pass graph: sqliteGraph({ path }) or graph: neo4jGraph({ url, username, password })"
+      );
+    }
+    return this.graph;
+  }
+  assertGraphCheckpointSupported(operation) {
+    if (!this.graph) return;
+    if (!this.graph.supportsFileSnapshot()) {
+      throw new GraphCheckpointNotSupportedError(this.graph.name, operation);
+    }
+  }
+  graphSnapshotDir(alongsidePath) {
+    return `${alongsidePath}.graph`;
+  }
+  async closeGraphForSnapshot() {
+    if (!this.graph || !this.graph.supportsFileSnapshot()) return false;
+    await this.graph.close();
+    return true;
+  }
+  async snapshotGraphAlongside(alongsidePath, operation) {
+    if (!this.graph) return;
+    if (!this.graph.supportsFileSnapshot()) {
+      throw new GraphCheckpointNotSupportedError(this.graph.name, operation);
+    }
+    const dataPath = this.graph.getDataPath();
+    if (!dataPath) return;
+    const dest = this.graphSnapshotDir(alongsidePath);
+    await this.graph.close();
+    try {
+      if (fs6__default.default.existsSync(dest)) {
+        fs6__default.default.rmSync(dest, { recursive: true, force: true });
+      }
+      if (fs6__default.default.existsSync(dataPath)) {
+        const stat = fs6__default.default.statSync(dataPath);
+        if (stat.isDirectory()) {
+          fs6__default.default.cpSync(dataPath, dest, { recursive: true });
+        } else {
+          fs6__default.default.mkdirSync(dest, { recursive: true });
+          fs6__default.default.cpSync(dataPath, path7__default.default.join(dest, path7__default.default.basename(dataPath)));
+          const parent = path7__default.default.dirname(dataPath);
+          const base = path7__default.default.basename(dataPath);
+          for (const entry of fs6__default.default.readdirSync(parent)) {
+            if (entry === base) continue;
+            if (entry.startsWith(base)) {
+              fs6__default.default.cpSync(
+                path7__default.default.join(parent, entry),
+                path7__default.default.join(dest, entry),
+                { recursive: true }
+              );
+            }
+          }
+        }
+      }
+    } finally {
+      await this.graph.open();
+    }
+  }
+  async restoreGraphAlongside(alongsidePath, operation) {
+    if (!this.graph) return;
+    if (!this.graph.supportsFileSnapshot()) {
+      throw new GraphCheckpointNotSupportedError(this.graph.name, operation);
+    }
+    const dataPath = this.graph.getDataPath();
+    if (!dataPath) return;
+    const src = this.graphSnapshotDir(alongsidePath);
+    if (!fs6__default.default.existsSync(src)) {
+      return;
+    }
+    if (fs6__default.default.existsSync(dataPath)) {
+      fs6__default.default.rmSync(dataPath, { recursive: true, force: true });
+    }
+    const entries = fs6__default.default.readdirSync(src);
+    if (entries.length === 1 && entries[0] === path7__default.default.basename(dataPath)) {
+      fs6__default.default.mkdirSync(path7__default.default.dirname(dataPath), { recursive: true });
+      fs6__default.default.cpSync(path7__default.default.join(src, entries[0]), dataPath, { recursive: true });
+    } else {
+      fs6__default.default.mkdirSync(path7__default.default.dirname(dataPath), { recursive: true });
+      fs6__default.default.cpSync(src, dataPath, { recursive: true });
+    }
+  }
+  async hydrateRelated(memoryId, options) {
+    const graph = this.requireGraph("getRelated");
+    const related = await graph.getRelated(memoryId, options);
+    const { storage, organization } = await this.requireReady();
+    const out = [];
+    for (const stub of related) {
+      const row = await storage.getMemoryById(stub.id, organization);
+      if (row) {
+        out.push(toMemoryRecord(row));
+      } else {
+        out.push(stub);
+      }
+    }
+    return out;
+  }
   requireMemoryDbPath() {
     if (!this.memoryDbPath || this.memoryDbPath === ":memory:") {
       throw new ConfigurationError(
@@ -8147,7 +9259,7 @@ var Wolbarg = class {
         }
       );
     }
-    return path5__default.default.isAbsolute(this.memoryDbPath) ? this.memoryDbPath : path5__default.default.resolve(process.cwd(), this.memoryDbPath);
+    return path7__default.default.isAbsolute(this.memoryDbPath) ? this.memoryDbPath : path7__default.default.resolve(process.cwd(), this.memoryDbPath);
   }
 };
 function wolbarg(options) {
@@ -8243,10 +9355,16 @@ function sqliteTelemetry(url) {
 function sqliteCheckpoint(directory) {
   return new SqliteCheckpointProvider({ directory });
 }
+function sqliteGraph(options) {
+  return new SqliteGraphProvider(options);
+}
+function neo4jGraph(options) {
+  return new Neo4jGraphProvider(options);
+}
 function createTelemetryProvider(config) {
   if (config.database.provider !== "sqlite") {
     throw new ConfigurationError(
-      `Unsupported telemetry provider "${config.database.provider}". Only "sqlite" is implemented in v0.3.0.`
+      `Unsupported telemetry provider "${config.database.provider}". Only "sqlite" is implemented. Telemetry supports sqlite or postgres only \u2014 not kuzu/neo4j.`
     );
   }
   const url = config.database.url ?? config.database.connectionString ?? "";
@@ -8708,19 +9826,23 @@ exports.ConfigurationError = ConfigurationError;
 exports.DatabaseError = DatabaseError;
 exports.EmbeddingError = EmbeddingError;
 exports.FixedChunkingStrategy = FixedChunkingStrategy;
+exports.GraphCheckpointNotSupportedError = GraphCheckpointNotSupportedError;
 exports.HeadingChunkingStrategy = HeadingChunkingStrategy;
 exports.InitializationError = InitializationError;
 exports.LlmCompressionProvider = LlmCompressionProvider;
 exports.MarkdownChunkingStrategy = MarkdownChunkingStrategy;
 exports.MemoryNotFoundError = MemoryNotFoundError;
+exports.Neo4jGraphProvider = Neo4jGraphProvider;
 exports.NoopTelemetryProvider = NoopTelemetryProvider;
 exports.ParagraphChunkingStrategy = ParagraphChunkingStrategy;
 exports.PostgresStorageProvider = PostgresStorageProvider;
 exports.ProviderNotConfiguredError = ProviderNotConfiguredError;
+exports.SDK_VERSION = SDK_VERSION;
 exports.SentenceChunkingStrategy = SentenceChunkingStrategy;
 exports.SqliteCheckpointProvider = SqliteCheckpointProvider;
 exports.SqliteDatabaseProvider = SqliteDatabaseProvider;
 exports.SqliteEventDatabase = SqliteEventDatabase;
+exports.SqliteGraphProvider = SqliteGraphProvider;
 exports.SqliteStorageProvider = SqliteStorageProvider;
 exports.SqliteTelemetryProvider = SqliteTelemetryProvider;
 exports.StorageLockedError = StorageLockedError;
@@ -8746,6 +9868,7 @@ exports.geminiVision = geminiVision;
 exports.jinaReranker = jinaReranker;
 exports.lmStudioEmbedding = lmStudioEmbedding;
 exports.meta = meta;
+exports.neo4jGraph = neo4jGraph;
 exports.ollamaEmbedding = ollamaEmbedding;
 exports.ollamaLlm = ollamaLlm;
 exports.openRouterEmbedding = openRouterEmbedding;
@@ -8762,6 +9885,7 @@ exports.runBenchmark = runBenchmark;
 exports.sqlite = sqlite;
 exports.sqliteCheckpoint = sqliteCheckpoint;
 exports.sqliteConfig = sqliteConfig;
+exports.sqliteGraph = sqliteGraph;
 exports.sqliteTelemetry = sqliteTelemetry;
 exports.summarizeBenchmark = summarizeBenchmark;
 exports.tesseract = tesseract;