Optional graph layer for Wolbarg — link memories and entities, traverse relations, and attach related hits to recall. SQLite for local/dev, Neo4j for production.

What is it?

An optional graph beside your vector/memory store. Memories (and entities) become nodes; directed relations become edges. Use it when agents need “what else is connected to this fact?” — not only “what is similar?”.

Graph does not replace storage. Semantic search still runs on SQLite/Postgres; the graph adds structure on top.

Introduced in 0.5.0 — see What's New.

Why use it?

Link a ticket memory to a policy memory (depends_on, cites, contradicts, …)
Walk a short path from a recalled hit to related facts
Attach entity nodes (people, products, orgs) to memories
Keep the same app code when moving from local SQLite graph → Neo4j

Quick start

import {
  wolbarg,
  openaiEmbedding,
  sqlite,
  sqliteGraph,
} from "wolbarg";

const ctx = wolbarg({
  organization: "my-org",
  storage: sqlite("./data/memory.db"),
  embedding: openaiEmbedding({
    apiKey: process.env.OPENAI_API_KEY!,
    model: "text-embedding-3-small",
  }),
  graph: sqliteGraph({ path: "./data/graph.db" }),
});

await ctx.ready();

const a = await ctx.remember({
  agent: "support",
  content: { text: "Customer prefers email over chat." },
});
const b = await ctx.remember({
  agent: "support",
  content: { text: "Refund SLA is 5 business days." },
});

await ctx.linkMemories(a.id, b.id, "related_to");

const related = await ctx.getRelated(a.id, { depth: 1 });
// related → [b, …]

const hits = await ctx.recall({
  query: "customer contact preference",
  includeGraph: true,
});
// hits[0].related — neighbors of the top hit

Prefer isolating factories in a providers/ folder so swapping backends is a one-file change — see Installation → Project layout.

Backends

Backend	Factory	Best for	Peer
SQLite	`sqliteGraph({ path })`	Local / single-node / checkpoints	None (`node:sqlite`)
Neo4j	`neo4jGraph({ url, username, password, database? })`	Shared / multi-host production	`neo4j-driver`

npm install neo4j-driver   # only for Neo4j

import { neo4jGraph } from "wolbarg";

graph: neo4jGraph({
  url: process.env.NEO4J_URL!,
  username: process.env.NEO4J_USER!,
  password: process.env.NEO4J_PASSWORD!,
  database: "neo4j", // optional
})

Config object form also works — see Configuration → graph.

Portability contract

Portable (same behavior on SQLite and Neo4j):

linkMemories / unlink (provider)
getRelated
upsertEntity / linkEntityToMemory (on the provider)
deleteMemory cascade used by forget / clear

Not portable:

API	SQLite	Neo4j
`query(cypher, params)`	Hard error	Supported
`checkpoint` / `export` / `import` / `rollback` with graph	File snapshot of graph DB	Throws `GraphCheckpointNotSupportedError`

Write application logic against typed methods only. Use Cypher only when you intentionally target Neo4j.

Schema (SQLite graph)

Graph data lives in a separate SQLite file from the memory store by default:

graph_nodes — memory | entity nodes (ref_id, optional name, metadata)
graph_edges — directed edges (relation, metadata)
Indexes on edge endpoints for recursive walks

getRelated uses a bounded recursive CTE (default depth 1, max 16) with cycle detection. Writes use the same BEGIN IMMEDIATE retry path as storage — see Concurrency.

Facade methods

Method	Docs
`linkMemories(fromId, toId, relation, metadata?)`	linkMemories()
`getRelated(memoryId, options?)`	getRelated()
`recall({ includeGraph: true })`	recall()

Calling graph methods without configuring graph throws ProviderNotConfiguredError — see Errors.

Cascade deletes

When graph is configured, forget and clear remove the matching graph memory node and incident edges so the graph cannot point at deleted memories.

Studio

Inspect the graph visually in Wolbarg Studio — the graph canvas shows memories, entities, and edge labels (about, references, follows, …).

Wolbarg Studio graph canvas

Connect Studio to your graph backend (SQLite / Neo4j / snapshot) under Settings. Full walkthrough with dashboard and Trace Explorer shots: Observability & Studio. Release notes: What's New in 0.5.0.

Graph memory