nicia-ai/typegraph: The Knowledge Graph for TypeScript

The Knowledge Graph for TypeScript

Summary

TypeGraph is a TypeScript-first embedded knowledge graph library that stores property-graph data inside an existing SQLite or PostgreSQL database. It uses Zod schemas to define nodes and edges and exposes a fluent, compile-time-checked query API for traversal, filtering, and composition. It is published on npm as @nicia-ai/typegraph under an MIT license.

What it is useful for

• Building knowledge graphs and RAG context layers on top of a regular SQL database, with no separate graph service.
• Recording auditable agent memory, decision replay, and bitemporal forensics via the documented temporal queries.
• Modeling identity/permissions and other relationship-heavy domains where richer semantics than a simple join table are needed.
• Starting on SQLite and later moving the same graph definition to PostgreSQL, or to edge/serverless targets such as Cloudflare Durable Objects, D1, libSQL, or bun:sqlite.

The README is explicit about what it does not target: distributed graph processing, broad graph-data-science suites (the focused Graph Algorithms API covers shortest path, reachability, neighborhoods, degree, exact WCC, label propagation, and PageRank, but not broader community/centrality work), and billion-scale graphs that need a dedicated engine.

How engineers can use it

The documented install command pulls the library plus its peers:

npm install @nicia-ai/typegraph zod drizzle-orm better-sqlite3
npm install -D @types/better-sqlite3

Nodes, an edge, and a graph are then declared with Zod, as shown in the README quick start:

const Person = defineNode("Person", {
  schema: z.object({ name: z.string(), role: z.string().optional() }),
});
const Project = defineNode("Project", {
  schema: z.object({ name: z.string(), status: z.enum(["active", "done"]) }),
});
const worksOn = defineEdge("worksOn");

const graph = defineGraph({
  id: "my_app",
  nodes: { Person: { type: Person }, Project: { type: Project } },
  edges: { worksOn: { type: worksOn, from: [Person], to: [Project] } },
});

const store = await createLocalSqliteStore(graph);

Records are created through the schema-derived store.nodes.* and store.edges.* APIs, and a typed traversal reads back results:

const results = await store
  .query()
  .from("Person", "p")
  .traverse("worksOn", "e")
  .to("Project", "proj")
  .select((ctx) => ({ person: ctx.p.name, project: ctx.proj.name }))
  .execute();

Other documented entrypoints include @nicia-ai/typegraph/postgres/pglite for a PGlite-backed PostgreSQL store, the /adapters/drizzle/... family for bring-your-own Drizzle connections, and @nicia-ai/typegraph/core or /backend for sharing schemas or building custom backends. Vector and hybrid search are documented for pgvector, sqlite-vec, and libSQL/Turso.

Documented caveats to be aware of: drizzle-orm is an optional peer dependency, and the README notes that Drizzle-aware entrypoints will surface a MISSING_PEER_DEPENDENCY error if it is not installed. The README directs readers to its Getting Started, Queries, and Graph Merge docs for production schema management, recursive traversals, and runtime schema extension via JSON-driven Graph Extensions; the llms.txt and llms-small.txt/llms-full.txt files are available for coding-agent workflows.