The engine. You ship the assistant.
Graphorin is the open-source TypeScript framework for long-living personal AI assistants: a trainer, tutor, advisor, or co-pilot that remembers, endures, and stays yours. Runs local-first, on your own machine.
// give your assistant a memory, then just talk to it
import { createAgent } from '@graphorin/agent';
const coach = createAgent({
name: 'coach',
instructions: 'You are a personal trainer.',
provider,
memory, // SQLite on your disk
tools: memory.tools, // lets the model save + recall facts
});
for await (const e of coach.stream(process.argv[2]))
if (e.type === 'text.delta') process.stdout.write(e.delta);npx tsx assistant.ts "Did squats today: 5x5 at 100 kg"Logged. 100 kg for 5 is a new personal best. Nice work.// two days later · a new process, the same memorynpx tsx assistant.ts "What's the plan for today?"Last time you hit 100 kg for 5, and sleep ran short this week. Warm up, then 3x5 at 102.5 kg and stop there.
Example transcript. Here the model decides when to save or recall; the quickstart wires the deterministic pattern.
Most assume a managed dashboard, hosted inference, and phone-home telemetry by default. We wanted the opposite: an audit-friendly, air-gap-compatible foundation that an enterprise compliance team can sign off in an afternoon.
Most frameworks specialise in one frontier: agent memory, the agent loop, or durable execution. Few own all three together. Build a real personal assistant on any of them and you end up stitching four libraries together.
Graphorin is one composable surface across all of it: the agent loop, six-tier memory, durable workflow, secrets, observability, sandbox, sessions, and an optional standalone server when you need to expose your assistant over a network.
DeliveryA daemon with REST, WebSocket, and SSE. A CLI. A typed client.
@graphorin/server@graphorin/cli@graphorin/clientRuntimeThe agent loop and the durable step-graph workflow engine.
@graphorin/agent@graphorin/workflowMemorySix tiers, bitemporal facts, background consolidation, sessions.
@graphorin/memory@graphorin/sessionsSurfaceDefer-loaded tools, signed skills, an in-core MCP client.
@graphorin/tools@graphorin/skills@graphorin/mcpPersistenceSQLite or SQLCipher storage, local embeddings, any LLM behind one interface.
@graphorin/store-sqlite@graphorin/provider@graphorin/embedder-transformersjsCross-cuttingSecrets, traces, and cost caps woven through every layer.
@graphorin/security@graphorin/observability@graphorin/pricingFoundationThe contracts everything else implements.
@graphorin/coreNo account. No API key. No cloud dashboard. Install the packages, point the provider at a local model through Ollama, and the file on the right runs exactly as written, top to bottom.
import { createAgent } from '@graphorin/agent';
import { createMemory, defineAutoRecallStrategy } from '@graphorin/memory';
import { createProvider, ollamaAdapter } from '@graphorin/provider';
import { createSqliteStore } from '@graphorin/store-sqlite';
import { createTransformersJsEmbedder } from '@graphorin/embedder-transformersjs';
// 1 · everything lives in one local file
const sqlite = await createSqliteStore({ path: './assistant.db' });
await sqlite.init();
// 2 · six-tier memory, embeddings run on your machine
const memory = createMemory({
store: sqlite.memory,
embeddings: sqlite.embeddings,
embedder: createTransformersJsEmbedder(),
contextEngine: {
// a loopback provider may see internal facts
privacy: { providerTrust: 'loopback' },
// recall stored facts into every prompt, not only when the model asks
factsAutoRecall: {
topK: 5,
strategy: defineAutoRecallStrategy({
id: 'every-turn',
evaluate: ({ lastUserMessage }) => ({
factsTriggered: lastUserMessage.trim().length > 0,
reason: 'every-turn',
}),
}),
},
},
});
// 3 · a local model through Ollama: no API key, no cloud
const provider = createProvider(
ollamaAdapter({ baseUrl: 'http://127.0.0.1:11434', model: 'qwen2.5:7b-instruct-q4_K_M' }),
{ acceptsSensitivity: ['public', 'internal'] },
);
const agent = createAgent({
name: 'hello',
instructions: 'Be brief and helpful.',
provider,
memory,
userId: 'u1',
sessionId: 's1',
tools: memory.tools, // the model can also search + save facts mid-chat
autoAssembleContext: true, // recalled facts ride in automatically
});
// 4 · teach it a durable fact: an explicit write, straight to SQLite
await memory.semantic.remember(
{ userId: 'u1' },
{ text: 'Front squat working set: 5x5 at 100 kg.' },
);
// 5 · stream the answer, token by token: the fact is already in context
for await (const event of agent.stream('What should I lift today?'))
if (event.type === 'text.delta') process.stdout.write(event.delta);
Zero version pings. Zero analytics. Zero crash uploads. Zero npm postinstall
network calls. A continuous-integration check fails the build the moment anyone slips.
This isn't “mostly local”. It's a hard rule.
Six distinct layers, each with its own lifecycle. Old facts are superseded, never silently overwritten, and bitemporal history lets you ask what was true as of last March. A background consolidator distils long conversations into long-term knowledge.
Workflows pause for an overnight approval, resume on a different machine, and continue exactly where they left off. Tools execute exactly once, even if the process dies mid-call. Human-in-the-loop is a primitive, not an afterthought.
Switch models with a one-line change. Use a frontier API today, an OpenAI-compatible server tomorrow, Ollama or an in-process GGUF model the day after, without rewriting your assistant. Local LLMs are first-class, not a fallback.
A secret-value type that cannot be accidentally logged, serialised, or displayed. OS keychain integration and OAuth 2.1 with PKCE. Cryptographically signed skills. A tamper-evident audit log for every privileged operation.
OpenTelemetry-native traces with the GenAI semantic conventions for every LLM call, tool, memory write, and workflow step. A mandatory redaction layer keeps secrets and PII out of your traces, even if you forget.
Zero any in public APIs. Schemas flow through tools, memory blocks, and
structured outputs. Streaming-first by design: every operation is a typed
AsyncIterable of events your UI can render as they happen.
Most frameworks treat memory as one undifferentiated bag. Graphorin treats it as six layers, each with its own lifecycle, conflict-resolution strategy, and privacy posture. Together they give your assistant a memory it can actually live with, for years.
Short, structured blocks holding what the assistant is doing right now: persona, current task, immediate context.
milliseconds to minutesThe rolling message log of the current conversation. The thread you're inside, with all of its turn-by-turn context.
minutes to hoursThings that happened: decisions, events, milestones, captured with proper bitemporal validity. The assistant's autobiography.
days to yearsFacts about you, the world, the task. Conflicts resolved through a multi-stage pipeline. Old facts superseded, never destroyed.
weeks to permanentHow to do things: workflows, recipes, learned patterns. The assistant gets better at the tasks it does most often.
grows over timeCommon knowledge across multiple agents in the same household, team, or organisation, with private layers for each individual.
cross-agent, lastingExact dedup, embedding three-zone, heuristic, then subject/predicate. No coin flips. Every decision is auditable.
Dense vectors plus full-text, fused with Reciprocal Rank Fusion. Late-chunking retrieval, an entity graph with one-hop expansion, pluggable rerankers.
Light, standard, and deep phases distil sessions into long-term memory. A built-in cost cap means it can never run away with your bill.
Untrusted content is quarantined with provenance attached, and promotes to trusted memory only after validation. Privacy tags flow through traces and exports, with redaction on by default.
Remembers your injury history, your last six months of workouts, your nutrition preferences, and your favourite phrasing.
Knows what your child mastered last week, what they struggled with, and adjusts every lesson accordingly.
Has watched a year of your spending, understands your goals, and waits for your approval before doing anything irreversible.
Lives alongside your team, knows your customers and contracts, and quietly drafts follow-ups overnight.
Builds up a multi-month understanding of a topic, never forgets a citation, and surfaces the right paper at the right time.
Several family members talk to it, each with their own private memory, plus a shared layer for the things that concern everyone.
Embed Graphorin directly in any Node.js process. Your application owns the lifecycle, which is perfect for desktop apps, CLIs, scripts, and short-lived services.
Promote your assistant to a long-lived daemon with a network API the moment it has to outlive a terminal. Same code, different process model.
The promise
Eighteen design principles, encoded in the repository. If a feature contradicts a principle, the feature loses. No drift. No scope creep. No surprises.
It will be won by whoever earns the user's trust over time: by remembering what matters, forgetting what doesn't, never leaking what's private, and being there next year when the user comes back. That is a framework problem before it is a product problem, and the frameworks that exist today were not designed for it. So we designed one that is.
Graphorin is pre-1.0 software under active development. The architecture and the eighteen design principles are stable; public APIs can still shift between minor releases, and every breaking change ships with notes in the changelog. It is a solid fit today for personal assistants, internal tools, and pilots, and 1.0 is the contract for long-term API stability.
Any. A frontier API, any OpenAI-compatible endpoint, Ollama, or an in-process GGUF model through llama.cpp, all behind one provider interface. Switching providers is a one-line change, and local models are first-class, not a fallback.
The framework itself makes zero implicit network calls: no version pings, no analytics, no crash uploads, and a CI check enforces that rule on every commit. The only traffic is the traffic you configure. Point the provider at a cloud model and your prompts go there; run a local model and nothing leaves at all.
Node.js 22 or newer. No account, no API key, no cloud dashboard: storage is a local SQLite file, embeddings run on your machine, and a local model through Ollama completes a fully offline setup.
A vector database gives you similarity search. A memory model also decides what to keep, which fact wins in a conflict, and what to forget. Graphorin layers six tiers (working, session, episodic, semantic, procedural, shared), each with its own lifecycle and conflict-resolution strategy, plus hybrid retrieval and a background consolidator on top.
Yes. MCP support is first-class, so any MCP server plugs in directly. Typed tool definitions, cryptographically signed skills, and an optional standalone server with REST, WebSocket, and SSE cover the rest.
Open source. MIT licensed. Local-first. No account, no API key to start. The engine is ready when you are.