TypeGraph
TypeScript-first embedded knowledge graph library.
TypeGraph brings property graph modeling and practical ontology support to your existing SQLite or PostgreSQL
database. Define nodes and edges with Zod, query with a fluent TypeScript API, and keep graph + app data in one
deployment.
## Why teams use it
- Keep graph data in your existing SQL database (no separate graph service)
- Model richer semantics with `subClassOf`, `implies`, `inverseOf`, and `disjointWith`
- Traverse relationships with compile-time type safety
- Run vector and hybrid search across every backend — pgvector, sqlite-vec, and libSQL/Turso native vectors
- Start with SQLite, move to PostgreSQL without changing your graph definition
- Evolve the schema at runtime from agent-proposed JSON — no redeploy
([Graph Extensions](https://typegraph.dev/graph-extensions))
- Reconstruct valid-time and recorded-time history with bitemporal reads
([Temporal queries](https://typegraph.dev/queries/temporal))
## Best fit
TypeGraph works well for:
- Knowledge graphs and RAG context modeling
- Auditable agent memory, decision replay, and bitemporal forensics
- Identity/permissions and other relationship-heavy domain models
- Applications that want graph semantics without extra infrastructure
TypeGraph is not designed for:
- Distributed graph processing
- Broad graph-data-science suites—its focused
[Graph Algorithms](https://typegraph.dev/graph-algorithms) API includes
shortest path, reachability, neighborhoods, degree, exact WCC, deterministic
label propagation, and global/personalized PageRank, but not broad community
detection or centrality suites
- Billion-scale graphs requiring dedicated graph-engine performance
## Installation
```bash
npm install @nicia-ai/typegraph zod drizzle-orm better-sqlite3
npm install -D @types/better-sqlite3
```
For edge/serverless environments (Cloudflare Durable Objects, D1, libsql,
bun:sqlite), see the docs:
[Edge and Serverless](https://typegraph.dev/integration#edge-and-serverless).
## Quick Start
```typescript
import { z } from "zod";
import { defineEdge, defineGraph, defineNode } from "@nicia-ai/typegraph";
import { createLocalSqliteStore } from "@nicia-ai/typegraph/sqlite/local";
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);
const alice = await store.nodes.Person.create({ name: "Alice", role: "Engineer" });
const website = await store.nodes.Project.create({ name: "Website", status: "active" });
await store.edges.worksOn.create(alice, website, {});
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();
console.log(results);
// [{ person: "Alice", project: "Website" }]
```
For production schema management, see:
[createStoreWithSchema](https://typegraph.dev/getting-started#store-creation-which-function-to-use).
The managed SQLite entrypoint provisions the schema and returns the complete,
schema-derived `Store` API without exposing Drizzle types. PostgreSQL consumers
can use the equivalent `createLocalPgliteStore` from
`@nicia-ai/typegraph/postgres/pglite`. Bring-your-own-connection integrations
live under the explicit `/adapters/drizzle/...` entrypoints.
Packages that only define or share graph schemas can import the DSL and its
schema-derived types from `@nicia-ai/typegraph/core`. Custom backend and search
strategy authors can use the complete Drizzle-free contract vocabulary from
`@nicia-ai/typegraph/backend`.
`drizzle-orm` is an optional peer dependency. `@nicia-ai/typegraph/sqlite/local`
and `@nicia-ai/typegraph/postgres/pglite` load it only when their factory is
called and refuse with a typed `ConfigurationError`
(`MISSING_PEER_DEPENDENCY`) naming the package and the install command
(`npm install drizzle-orm`) when it is absent. The six explicit
`/adapters/drizzle/...` entrypoints expose Drizzle-native backends, connections,
or schema builders and load `drizzle-orm` when the module is evaluated. Importing
one without the peer installed therefore surfaces the raw module-resolution
error, which names the same package.
## Learn More
- Docs: [typegraph.dev](https://typegraph.dev)
- Overview: [What is TypeGraph?](https://typegraph.dev/overview)
- Setup: [Getting Started](https://typegraph.dev/getting-started)
- Query builder: [Queries Overview](https://typegraph.dev/queries/overview)
- Temporal and bitemporal history: [Temporal queries](https://typegraph.dev/queries/temporal)
- Application patterns: [Common Patterns](https://typegraph.dev/recipes)
- Complete examples: [packages/typegraph/examples](packages/typegraph/examples/)
- Project docs: [Testing](docs/TESTING.md), [Release Process](docs/RELEASE.md)
## LLM/Coding Agent Support
TypeGraph publishes agent-friendly documentation following the [llms.txt](https://llmstxt.org/) convention:
- Landing page: [LLM Support](https://typegraph.dev/llm-support/)
- Index: [llms.txt](https://typegraph.dev/llms.txt)
- Core docs: [llms-small.txt](https://typegraph.dev/llms-small.txt)
- Full docs: [llms-full.txt](https://typegraph.dev/llms-full.txt)
- Examples: [examples.txt](https://typegraph.dev/_llms-txt/examples.txt)
Recommended retrieval order: `llms-small` → `llms-full` → `examples`.
## License
MIT