@graphorin/skills

---

Graphorin is a foundation layer for higher-level assistant products — a personal trainer, a personal tutor, a personal business assistant, a personal financial advisor, and so on. It is intentionally a framework, not a product: assistant bots are built on top of it.

Table of contents

• Why Graphorin?
• Status
• Use cases
• What's in the box
• Quick start
• Architecture at a glance
• Packages
• Privacy & no-phone-home
• Direct dependencies
• Documentation
• Repository layout
• Release readiness
• Contributing
• Code of Conduct
• Security
• License
• Maintainer & contact

Why Graphorin?

• Long-living, not single-shot. Assistants built on Graphorin are designed to remember, endure, and stay yours — a six-tier memory model and a durable workflow runtime mean state survives a process restart and finishes on a different machine if it has to.
• Local-first by default. Zero implicit network calls. No version pings, no usage analytics, no auto-update phone-home. The only outbound traffic is the traffic your code initiates — verified by a continuous-integration check that fails the build on any forbidden socket call.
• Vendor-neutral on LLMs. A single Provider abstraction adapts cloud models, local Ollama daemons, OpenAI-compatible HTTP servers, and in-process GGUF execution. Switch models with a one-line change.
• Streaming-first API. Every operation is a typed AsyncIterable<AgentEvent> — tokens, tool calls, memory writes, handoffs, fallback transitions and human approvals all surface as events your UI can react to.
• Type-safe end-to-end. Zero any in public APIs. Schemas flow through tools, memory blocks, and structured outputs. Discriminated-union events come with exhaustive assertNever(...) checks.
• Privacy and security as primitives. A SecretValue type that cannot be accidentally logged, a SecretRef URI scheme, OS keychain integration, OAuth 2.1 with PKCE, sensitivity-aware payload tagging, optional encryption-at-rest, and a SHA-256 hash-chained audit log.
• Embed or run as a daemon. Use any package as a library inside your Node.js process, or promote your assistant to the optional standalone server with REST + WebSocket + SSE fallback and durable triggers.

Status

Graphorin is currently on the v0.5.0 pre-release line. The framework follows lockstep versioning across all @graphorin/* packages while the framework is on the 0.x line; once it reaches 1.0, optional packages and adapters are versioned independently.

Pre-1.0, minor bumps may carry breaking changes and patch bumps cover everything else (the industry pre-1.0 norm). See CHANGELOG.md for the authoritative rollup.

Published packages will appear on the npm registry under the @graphorin/* scope as each implementation phase completes — see the documentation at https://docs.graphorin.com for the rollout details.

Use cases

Graphorin is the engine. You ship the assistant. The framework is intentionally domain-agnostic so the same primitives can power a wide range of personal AI products:

• Personal trainer — multi-week training plans, progressive overload memory, habit tracking.
• Personal tutor — long-running learner profiles, spaced repetition, durable lesson workflows.
• Personal business assistant — meeting prep, follow-ups, contact memory, durable approval flows.
• Personal financial advisor — bi-temporal facts, sensitivity-aware payloads, audited tool execution.
• Health & wellness companions, knowledge workers, research copilots — anywhere you need an assistant that remembers across sessions and survives process restarts.

What Graphorin does not ship (intentional): channel adapters (Telegram, Slack, iMessage, WhatsApp), a UI, a SaaS, or a model-serving stack. Those belong to higher-level assistant products built on top of Graphorin.

What's in the box

Area	Capability
Memory	Six-tier memory system — working / session / episodic / semantic / procedural / shared, with pluggable storage and a background consolidation pipeline.
Workflow	Durable step-graph runtime with checkpoints, pause / resume across process restarts, and human-in-the-loop primitives.
Local-first	SQLite + the sqlite-vec extension + FTS5; multilingual embeddings via @huggingface/transformers; cloud is opt-in.
Privacy	Zero default telemetry — no phone-home, no version pings, no analytics. Verified by a CI check.
Providers	Multi-vendor LLM access through Graphorin's own Provider interface, built on top of the Vercel AI SDK.
Tools / Skills / MCP	Typed tools, a SKILL.md packaging-format-compatible loader with three-tier progressive disclosure, and an in-core Model Context Protocol client.
Observability	OpenTelemetry-native tracing with the GenAI Semantic Conventions, sensitivity-aware redaction, and replay.
Secrets	SecretValue wrapper, SecretRef URI scheme, OS keychain integration, optional encryption-at-rest.
Two-layer delivery	Embed any package as a library, or run @graphorin/server as a daemon with REST + WebSocket and durable triggers.

Quick start

Note. The published @graphorin/* packages are not yet available on the npm registry — they will land as each implementation phase of the v0.5.0 line completes. The instructions below describe how to work with the framework once the relevant packages have been released. The full quickstart lives at https://docs.graphorin.com/guide/quickstart.

Prerequisites

• Node.js 22.x LTS or newer (see .nvmrc).
• pnpm as the package manager (the project default — npm and yarn work for consumers of published @graphorin/* packages, but development of the framework itself uses pnpm).

From source

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

A 20-line "hello world" script that creates a memory-backed agent, streams tokens, and persists facts to local SQLite via local embeddings will be published with the v0.5.0 release. Until then, the same example is available in the Quickstart guide.

Architecture at a glance

Graphorin is built as a stack of focused packages. Each layer depends only on the layers below it, so you can pick the slice that matches your application — from a 20-line embedded agent up to a long-running daemon with REST + WebSocket and durable triggers.

Tier 6  Standalone server + DX     @graphorin/server · cli · protocol · client
Tier 5  Runtime                    @graphorin/agent · workflow
Tier 4  Memory & Sessions          @graphorin/memory · sessions
Tier 3  External surface           @graphorin/tools · skills · mcp
Tier 2  Persistence + Provider     @graphorin/store-sqlite · embedder-* · triggers · provider
Tier 1  Cross-cutting              @graphorin/security · observability · pricing
Tier 0  Foundation                 @graphorin/core (types · contracts · utilities · ESM-only)

Read the full architecture notes at https://docs.graphorin.com/guide/architecture.

Packages

The framework 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.

Package	Role
@graphorin/core	Core types, contracts, errors, ESM-only utilities.
@graphorin/security	Secrets, sandboxing, audit log, server-token auth, OAuth, supply chain.
@graphorin/observability	Tracing, redaction, eval interfaces.
@graphorin/pricing	Bundled LLM pricing snapshot + opt-in refresh.
@graphorin/store-sqlite	Default storage adapter on top of better-sqlite3 + sqlite-vec + FTS5.
@graphorin/embedder-transformersjs	Default in-process multilingual embedder.
@graphorin/embedder-ollama	First-class opt-in embedder against an Ollama daemon.
@graphorin/triggers	Background tasks — cron / interval / idle / event.
@graphorin/provider	Provider interface and adapters (Vercel AI SDK, Ollama, OpenAI-compatible HTTP, llama.cpp HTTP server).
@graphorin/provider-llamacpp-node	Companion package — in-process GGUF execution.
@graphorin/tools	Typed tool definitions and execution.
@graphorin/skills	SKILL.md packaging-format-compatible loader with three-tier progressive disclosure.
@graphorin/mcp	Model Context Protocol client (stdio + Streamable HTTP).
@graphorin/memory	Six-tier memory system with consolidation pipeline.
@graphorin/sessions	Hybrid session facade, agent registry, handoffs, JSONL export, replay.
@graphorin/agent	Agent runtime.
@graphorin/workflow	Durable workflow engine.
@graphorin/server	Optional standalone server with REST + WebSocket + SSE fallback.
@graphorin/cli	Operator CLI.
@graphorin/protocol	WebSocket protocol contract — graphorin.protocol.v1.
@graphorin/client	Browser-friendly client for the standalone server.
@graphorin/store-sqlite-encrypted	Optional SQLCipher v4 encryption-at-rest.
@graphorin/secret-1password	Optional reference adapter for the 1Password CLI.
@graphorin/reranker-transformersjs	Optional cross-encoder reranker via @huggingface/transformers.
@graphorin/reranker-llm	Optional LLM-judge reranker.
@graphorin/eslint-plugin	ESLint rules for projects that build on Graphorin.
@graphorin/evals	Optional evaluation primitives — scorers, datasets, reporters, regression detection.

The full per-package reference (status, role, public surface) lives at https://docs.graphorin.com/reference/packages.

Optional packages and adapters are versioned independently from the core lockstep release once the framework reaches 1.0.

Privacy & no-phone-home

Graphorin makes zero implicit network calls. The only outbound traffic Graphorin generates is the traffic your code initiates:

• LLM provider API calls
• MCP server connections
• OAuth flows
• Opt-in pricing-snapshot refresh
• Embedder model downloads
• Storage backend connections you wire yourself

The repository ships a pnpm run check-no-network CI check that fails if a non-allowed network call is introduced. See SECURITY.md and the Privacy promise for the full commitment.

Direct dependencies

Graphorin uses the libraries below at runtime. Each is integrated through public APIs — the framework's source tree does not bundle, fork, or redistribute any third-party source. The full list (with pinned versions, SPDX identifiers, and transitive notes) lives in THIRD_PARTY_NOTICES.md.

Library	License	Role inside Graphorin
ai (Vercel AI SDK)	Apache-2.0	Default cloud-LLM driver inside @graphorin/provider.
node-llama-cpp	MIT	In-process GGUF execution in @graphorin/provider-llamacpp-node.
js-tiktoken	MIT	Token counting in @graphorin/provider.
better-sqlite3	MIT	Default storage adapter in @graphorin/store-sqlite.
sqlite-vec	Apache-2.0 OR MIT	Vector-search SQLite extension.
@huggingface/transformers	Apache-2.0	Default in-process multilingual embedder.
hono	MIT	HTTP router for @graphorin/server.
@modelcontextprotocol/sdk	MIT	Underlying MCP client primitives.
@opentelemetry/*	Apache-2.0	Tracer + OTLP exporter.
@napi-rs/keyring	MIT	OS-keychain backend.
@node-rs/argon2	MIT	Argon2id KDF for the encrypted-file secrets store.
openid-client	MIT	OAuth 2.1 / PKCE flows.
commander	MIT	CLI argument parsing.
yaml	ISC	YAML parsing for SKILL.md frontmatter.
zod	MIT	Public-schema validation (peer dependency).

We are grateful to the maintainers of every project listed above. If you believe a component is missing from THIRD_PARTY_NOTICES.md, please open an issue or email the maintainer at step.oleksiy@gmail.com.

Documentation

The complete documentation is hosted at https://docs.graphorin.com.

Section	What you'll find
What is Graphorin?	Goals, non-goals, audience, and how to read the docs.
Installation	Prerequisites, the workspace-friendly install layout, peer dependencies.
Quickstart	A 20-line memory-backed agent that streams tokens and persists facts locally.
Architecture	The layered package model, end-to-end agent step, and two delivery modes.
Memory system	The six tiers, hybrid search, and the consolidation pipeline.
Workflow engine	Durable HITL, checkpoints, dynamic parallelism.
Providers	Vendor-neutral provider matrix and the middleware composer.
Tools, Skills, MCP	The external-surface primitives.
Standalone server	Promote your assistant to a daemon.
Observability	OpenTelemetry GenAI Semantic Conventions and the redaction layer.
Secrets	SecretValue, SecretRef, the keychain backend, and the audit log.
API reference	The auto-generated TypeScript surface.
Design principles	The eighteen principles encoded into the framework.
FAQ	Frequently asked questions.

Repository layout

packages/                Each @graphorin/* package lives here as its own workspace.
examples/                Stand-alone example apps that consume @graphorin/* packages.
benchmarks/              Latency, cost, and memory-simulation runners.
documentation/           Source for the public documentation site (https://docs.graphorin.com).
scripts/                 Repo-wide maintenance scripts (license check, no-network guard,
                         release-readiness gate, example-doc drift, …).
.github/                 GitHub Actions workflows, issue templates, and PR template.
.changeset/              Changesets configuration; one file per pending release entry.
CHANGELOG.md             Top-level rollup release notes (per-package CHANGELOGs live
                         in each package).
THIRD_PARTY_NOTICES.md   Runtime + build-time dependency attribution + license map.
SECURITY.md              Vulnerability disclosure process + cryptographic baselines.
NOTICE                   Top-level attribution file referenced by the MIT LICENSE.
AUTHORS.md               Project authorship.

Release readiness

The repository ships a single pnpm run mvp-readiness entry point that runs every release-readiness gate sequentially: lint, typecheck, build, test, the no-implicit-network guard, the SPDX license allowlist, the Skills-format snapshot drift check, and a workspace audit (consistent v0.5.0, MIT license, Oleksiy Stepurenko author, publishConfig.provenance: true, no private: true flag, engines.node set to >=22, required files present on disk).

The same command is invoked by the release.yml workflow before any package gets published.

Contributing

We welcome contributions. Please read CONTRIBUTING.md for the development workflow, conventions, commit format, and the local-checks checklist before opening a PR.

A few quick links:

• Open an issue
• Pull requests
• Project authorship
• Conventional Commits

By participating you agree to abide by the project's Code of Conduct.

Code of Conduct

Graphorin adopts the Contributor Covenant v2.1. The full text and the project's enforcement process live in CODE_OF_CONDUCT.md. Reports can be directed to the maintainer at step.oleksiy@gmail.com.

Security

Please do not open a public GitHub issue for security vulnerabilities. The preferred channel is a private GitHub Security Advisory at https://github.com/o-stepper/graphorin/security/advisories/new; you can also email step.oleksiy@gmail.com. See SECURITY.md for the full disclosure process and the project's cryptographic baselines.

License

Graphorin is released under the MIT License — a permissive license that allows commercial and non-commercial use, modification, and redistribution under the same terms. The full text lives in LICENSE.

Copyright (c) 2026 Oleksiy Stepurenko

The bundled NOTICE file is referenced by the MIT LICENSE and lists the attribution requirements that survive redistribution.

Maintainer & contact

Graphorin is created, owned, and maintained by Oleksiy Stepurenko.

• Email — step.oleksiy@gmail.com
• Website — https://graphorin.com
• Documentation — https://docs.graphorin.com
• Repository — https://github.com/o-stepper/graphorin

For commercial enquiries, partnerships, or anything that does not fit a public issue, please reach out by email.

---