Learn in branches. Remember in graphs.
Turn AI conversations into a knowledge graph that can branch, reference, converge, and keep growing.
English · 简体中文
Website · Quick start · ChatGPT login · Architecture
Graph Chat is a local-first, graph-native AI learning workspace. When an answer introduces an unfamiliar concept, you no longer have to bury every follow-up inside one increasingly tangled chat. Branch from any node, explore the idea in its own context, then reference multiple branches to form a new question. Every answer preserves the context and sources it actually used.
A regular chat remembers only what you asked next. Graph Chat also remembers where a question came from, which explanations it referenced, and how the resulting understanding reconnects to the main thread.
Starting question ──→ AI answer ──→ New concept A ──→ Deeper explanation
│
└────→ New concept B ──→ Examples and counterexamples
╲
Explanation of A ·········→ Synthesis ──→ New understanding
- Solid edges continue the current context.
- Dotted edges reference another branch for comparison, synthesis, or knowledge transfer.
- Nodes retain the question, answer, model, context snapshot, and source relationships.
- The graph is the durable knowledge structure; the Pi agent loop powers each answer.
| Capability | Current implementation |
|---|---|
| Graph-native learning | Infinite React Flow canvas, branch edges, cross-branch references, dragging, and search |
| Multiple knowledge graphs | Create, switch, rename, archive, and restore independent learning spaces |
| Precise follow-ups | Continue from any node or branch from selected text inside an answer |
| Branch synthesis | Reference multiple nodes so the model can compare, combine, or find a shared mechanism |
| Agent runtime | Pi agent core, streaming events, tool calls, automatic retry, and cancellation |
| ChatGPT subscription | Pi openai-codex device-code OAuth with automatic token refresh |
| Other models | OpenAI API, OpenRouter, Ollama, and OpenAI-compatible endpoints |
| Local data | Bun/Node SQLite, WAL, JSON export, and no external database |
| Local retrieval | SQLite FTS5 ranking across titles, prompts, summaries, content, tags, and source URLs |
| Eight interface languages | English-first application and documentation with persistent Simplified Chinese, Spanish, French, German, Japanese, Korean, and Traditional Chinese switching |
| Light and dark themes | Neutral, token-driven design system; follows the system appearance by default with a persistent top-right toggle |
| Resilient runs | Run-scoped streaming, explicit cancellation, and interrupted-run recovery |
| Privacy boundary | API keys stay in process; OAuth credentials stay in a private local file |
| Engineering quality | Strict TypeScript, Vitest, database and Pi runtime tests, and Playwright E2E |
Node.js 22.19+ is required:
npm install --global @everettjf/graphchat
graphchatFor a one-off launch, use npx @everettjf/graphchat. Bun users can use
bunx @everettjf/graphchat; both commands install the same package from the npm registry.
The easiest path needs no Bun, Node.js, or database installation:
- Download the archive for your platform from the latest GitHub release.
- Extract it.
- Run
graphchat(graphchat.exeon Windows).
Graph Chat opens http://127.0.0.1:4317 in your browser and stores its data in .graphchat/.
Bun 1.3+ is recommended. Node.js 22.19+ is also fully supported.
git clone https://github.com/everettjf/graphchat.git
cd graphchat
bun install
bun run graphchatThe graphchat launcher builds the application, starts the local service, and opens it in your browser. For hot-reload development, use bun run dev and open http://localhost:5173.
On first launch, Graph Chat creates an English example graph about RAG. The interface defaults to English and can be switched from the sidebar to Simplified Chinese, Spanish, French, German, Japanese, Korean, or Traditional Chinese. The selected language is shared with model runs, needs no credentials for the local demo, and is remembered on the device. The interface follows the system's light or dark appearance; use the top-right toggle to override it, and the choice is remembered too.
Production mode:
bun run build
bun run start:bunThe production server listens on http://127.0.0.1:4317 by default.
Prefer Node/npm? Use npm install, npm run dev, npm run build, and npm start. Bun and Pi do not conflict: Pi owns the agent harness, model integrations, OAuth flow, and tool loop, while Bun/Node runs the local HTTP server, SQLite, and frontend toolchain. Graph Chat uses bun:sqlite under Bun and node:sqlite under Node.
Graph Chat uses Pi's built-in openai-codex provider, so you can sign in with an eligible ChatGPT subscription instead of copying an API key.
- Open Models & settings in the lower-left corner.
- Choose ChatGPT.
- Select Sign in with ChatGPT.
- Enter the one-time device code on the OpenAI page.
- Return to Graph Chat. The connection status updates automatically; choose a model and save.
Pi initiates the login flow, and Graph Chat never receives your password. OAuth access and refresh credentials are stored in .graphchat/auth.json; they never appear in the browser API, logs, or graph exports. Signing out deletes the saved credential. Available Codex models and usage limits depend on your account, plan, and OpenAI's current policies.
OpenAI documents ChatGPT-plan access to Codex and notes that usage limits vary by plan. See Using Codex with your ChatGPT plan.
Copy .env.example to .env, or configure a provider directly in settings:
| Provider | Authentication | Default configuration |
|---|---|---|
| OpenAI | OPENAI_API_KEY or an in-process key |
Pi OpenAI provider |
| OpenRouter | OPENROUTER_API_KEY or an in-process key |
Pi OpenRouter provider |
| Ollama | No key required | http://127.0.0.1:11434/v1 |
| Custom | Optional in-process API key | Any OpenAI-compatible endpoint |
flowchart LR
UI["React 19 + tokenized light/dark UI<br/>React Flow"] --> API["Fastify API<br/>NDJSON streaming"]
API --> CTX["Context compiler<br/>parent path · references · selected text"]
CTX --> AGENT["Pi Agent Core<br/>model · tools · retry loop"]
AGENT --> MODELS["ChatGPT OAuth · OpenAI<br/>OpenRouter · Ollama"]
API --> DB[("Bun / Node SQLite<br/>graphs · nodes · edges")]
API --> AUTH[("Local auth.json<br/>OAuth only")]
Graph Chat does not send the entire graph to a model. The context compiler builds a bounded, traceable snapshot from the active parent node, explicit references, and selected text. Pi can use read-only graph tools to search or inspect more nodes, but it cannot modify the knowledge graph by itself.
Core code:
server/agent-runtime.ts— Pi agent, model routing, tools, and streaming eventsserver/openai-codex-auth.ts— ChatGPT device-code OAuth lifecycleserver/context-compiler.ts— graph context selection and budgetserver/credential-store.ts— atomic, minimally exposed local OAuth storagesrc/components/graph-canvas.tsx— graph interactions
- Default data directory:
.graphchat/ - Knowledge graph database:
.graphchat/graphchat.sqlite - ChatGPT OAuth credentials:
.graphchat/auth.json - API keys: current process only; never written to SQLite or
auth.json - Exports: graphs, nodes, and edges only; no credentials
- Default bind address:
127.0.0.1, not automatically exposed to the local network
Set GRAPHCHAT_DATA_DIR to change the data location. On platforms that support POSIX permissions, the OAuth file uses mode 0600. Protect this directory as you would any other local login credential.
For end-to-end acceptance of importing, branching, synthesis, knowledge
metadata, review, metrics, and export, see
docs/CORE_TESTING.md.
The versioned JSON backup and knowledge-asset fields are documented in
docs/GRAPHCHAT_FORMAT.md.
The local-only pilot metrics and privacy contract are documented in
docs/PRODUCT_VALIDATION.md.
The v0.2.0 release and migration checklist is in
docs/V020_TESTING.md.
bun run typecheck # TypeScript client and server
bun run test # unit, database, credential, and Pi runtime tests
bun run build # production build
bun run test:e2e # Playwright end-to-end tests
bun run test:all # complete verification- Hybrid retrieval with optional vector-backed ranking on top of local SQLite FTS
- Safe web capture, OCR, and incremental source refresh
- Optional end-to-end encrypted sync
- Collaborative sharing and read-only graph publishing
Issues, discussions, and pull requests are welcome. Read CONTRIBUTING.md first, then run bun run test:all (or npm run test:all) before submitting. New behavior should include corresponding tests. Report security issues privately as described in SECURITY.md.
MIT © Everett