Installation

Graphorin is published as a set of focused packages on the npm registry under the @graphorin/* scope. Packages are released lockstep at the same version while the framework is on the 0.x line.

Status

The @graphorin/* packages are published on the npm registry since v0.5.0. Watch the repository releases for new versions.

Prerequisites

• Node.js 22.12 or newer (the project pins >=22.12.0 - the first line where require(esm) is stable, so the packages are ESM-first but consumable from CommonJS via plain require()).
• A package manager - pnpm is the project default; npm and yarn work too for consumers of the published packages.
• ESM-only modules. Graphorin ships ESM with no separate CommonJS build. ESM projects ("type": "module" or .mjs files) import it; CommonJS projects can plain require() it on Node 22.12+ (require(esm) returns the same ESM instance - no dual-package hazard).

Supported platforms

The default stack pulls native modules (better-sqlite3, the sqlite-vec vector extension, and - via @graphorin/embedder-transformersjs - onnxruntime), so platform support is defined by their prebuilt binaries:

Tier	Platforms	Notes
CI-verified	Linux x64, macOS arm64, Windows x64	The full test suite runs on all three for every PR.
Prebuilt, not CI-run	Linux arm64, macOS x64	Every native dependency ships prebuilds; expected to work.
Partial	Windows arm64	Everything works except vector search: sqlite-vec publishes no windows-arm64 binary and is a loadable extension with no compile-from-source fallback, so @graphorin/store-sqlite throws SqliteVecMissingError at first vector use. FTS + keyword recall still work.

Additional platform notes:

• Native build fallback. If a prebuild is missing for an exotic target, better-sqlite3, the SQLCipher peer (better-sqlite3-multiple-ciphers), and isolated-vm compile from source - that requires a C++ toolchain and Python 3 at install time. sqlite-vec does not have this fallback (prebuilt-only).
• Windows shutdown semantics. graphorin start installs SIGTERM + SIGINT handlers for graceful drain. Windows never delivers a real SIGTERM, so use Ctrl+C / SIGINT (or the REST surface) to stop the daemon gracefully there; a service-manager TerminateProcess stop is abrupt.
• POSIX file-permission hardening (0600/0700 on secrets, spill files, traces) applies on Linux/macOS only; on Windows, confidentiality of those files rests on NTFS ACLs of the profile directory.

Quickest install (memory-backed local assistant)

Most assistants will need at minimum: the agent runtime, the memory facade, a provider, and a storage adapter.

pnpm add @graphorin/agent @graphorin/memory @graphorin/provider \
        @graphorin/store-sqlite @graphorin/embedder-transformersjs \
        zod

npm install @graphorin/agent @graphorin/memory @graphorin/provider \
            @graphorin/store-sqlite @graphorin/embedder-transformersjs \
            zod

yarn add @graphorin/agent @graphorin/memory @graphorin/provider \
        @graphorin/store-sqlite @graphorin/embedder-transformersjs \
        zod

zod is a non-optional peer dependency of every @graphorin/* package that touches a public schema. Bring whichever Zod version your application already uses (^3.23 or ^4).

Native modules and pnpm 10

First run fails with "Could not locate the bindings file"?

That is pnpm 10's build-script policy, not a broken install. The fix is the onlyBuiltDependencies block below.

better-sqlite3 (and the optional cipher peer better-sqlite3-multiple-ciphers) fetch their prebuilt native binaries from an install script. pnpm 10 and newer do not run dependency install scripts unless they are explicitly approved - the install still exits 0 and prints one easy-to-miss line:

Ignored build scripts: better-sqlite3@12.9.0.

The failure then surfaces only at the first database open. Graphorin raises a typed SqliteNativeBindingError naming this exact fix instead of the raw bindings.js stack:

{
  "pnpm": {
    "onlyBuiltDependencies": ["better-sqlite3", "sqlite-vec"]
  }
}

Add that block to your application's package.json (append "better-sqlite3-multiple-ciphers" when you enable encryption-at-rest), then reinstall - pnpm install && pnpm rebuild better-sqlite3 - or run the interactive pnpm approve-builds instead. The Graphorin repository itself carries this block, but pnpm scopes the approval to each project, so every consumer project needs its own copy.

npm and yarn run dependency install scripts by default; nothing to approve there.

Heads-up on install size: @graphorin/embedder-transformersjs requires the @huggingface/transformers peer, which pulls in onnxruntime-node and sharp - on the order of 350 MB of native runtime on top of the roughly 58 MB framework stack. That is the price of a fully in-process default embedder. If you run a local Ollama daemon anyway, swap it for @graphorin/embedder-ollama and the install stays near the 58 MB baseline. The Minimal profile guide covers this lean path end to end - including the embedder-less variant and the matching scaffold: 'minimal' agent posture for cheap always-on runs.

What each package does

See the Packages reference for the full list and one-line summaries. The most common starting set:

Package	Role
@graphorin/core	Type system + cross-package contracts. Pulled in transitively.
@graphorin/agent	Agent runtime - the typed model -> tool calls -> model loop.
@graphorin/memory	Six-tier memory system with the consolidation pipeline.
@graphorin/provider	Provider interface + adapters (Vercel AI SDK, Ollama, OpenAI-compatible, llama.cpp HTTP).
@graphorin/store-sqlite	Default storage adapter on top of better-sqlite3 + sqlite-vec + FTS5.
@graphorin/embedder-transformersjs	Default in-process multilingual embedder.

Optional add-ons

Add these as the assistant grows:

Package	When to add it
@graphorin/sessions	Multi-agent attribution, JSONL export, session replay.
@graphorin/workflow	Durable HITL workflows that survive process restarts.
@graphorin/tools	Custom typed tools beyond the eleven memory tools.
@graphorin/skills	Load skills from disk, npm packages, or Git repositories.
@graphorin/mcp	Talk to Model Context Protocol servers over stdio or Streamable HTTP.
@graphorin/security	Secrets (SecretValue, SecretRef), audit log, sandbox, OAuth.
@graphorin/observability	OpenTelemetry tracing + redaction.
@graphorin/server + @graphorin/cli	Run Graphorin as a daemon with REST + WebSocket.
@graphorin/embedder-ollama	First-class opt-in alternative embedder backed by an Ollama daemon.
@graphorin/provider-llamacpp-node	In-process GGUF execution via node-llama-cpp.
@graphorin/store-sqlite-encrypted	SQLCipher v4 encryption-at-rest.
@graphorin/secret-1password	Optional reference adapter for the 1Password CLI.
@graphorin/eslint-plugin	ESLint rules for projects that build on Graphorin.

Verifying the install

Once installed, the Quickstart walks you through a 20-line script that creates a memory-backed agent, streams tokens, and persists facts to local SQLite.

From source

For framework contributors:

git clone https://github.com/o-stepper/graphorin.git
cd graphorin
corepack enable
pnpm install --frozen-lockfile
pnpm -r build
pnpm -r test

See the Contributing guide for the full development workflow.