PersonalAI

A local-first, omni-capable AI assistant — like ChatGPT/Claude, but it runs open-source models on your hardware, works with your files and tools, and reaches external providers only when you explicitly configure and approve it.

PersonalAI is extensible (tools + MCP), structured-output-first (schemas everywhere), open-source-first (verified provenance only), and security-first (zero-trust toward tools, files, prompts, model outputs, and MCP servers).

Current state: the core product works end to end — streaming chat, document RAG with on-device OCR, continuously-synced folders with an entity knowledge graph (KAG), controllable memory, a security-first tool/MCP gateway, and single- or multi-agent answering with a tool-armed judge fact-check and evaluator-optimizer re-planning. The latest release is 0.9.0 (see the CHANGELOG). An MV3 browser extension is in early scaffolding.

What it does today:

• Streaming chat over local Ollama or remote OpenAI-compatible models.
• Chat with your documents — pgvector hybrid RAG with inline citations; scanned PDFs are OCR'd on-device (RapidOCR), and large attachments are indexed and retrieved, not dumped into the prompt.
• Continuously-synced folders — point Settings → Documents at local folders and they stay indexed as files change (add / edit / delete), fully on-device. A knowledge graph of the named entities across your corpus is built alongside the vector index and browsable in the UI.
• Memory you control — long-term + short-term, viewable / editable / erasable.
• Tool / MCP gateway, security-first — permissions, egress allowlist, append-only audit.
• Single- or multi-agent modes (planner → researcher → critic, with an optional tool-armed verifier) that fact-check the answer against independently-gathered evidence (retrieval + a bounded tool re-check) and can re-plan, with durable human-in-the-loop gates (answer-approval + blocking egress-approval).
• Transparency panel — activity timeline plus per-question context and token/time metrics.
• Always-on multi-tenancy (Postgres RLS) — local zero-login or hosted login + CSRF.

Learn more:

• What's new / full history: CHANGELOG
• How it works: the How it works section below, then the Documentation table.
• Deep dives: model suite, data extraction pipeline, context assembly.

Quickstart (local chat)

One command (easiest). From a fresh clone, make dev checks your tooling, installs deps, starts the database, and runs the backend + UI together with prefixed logs (Ctrl-C stops everything; the DB container keeps running). Use scripts/bootstrap.sh --no-run to set up without launching, or scripts/bootstrap.sh --help for options. macOS and Linux (use WSL2 on Windows).

make dev                     # deps check + install + db + backend + UI, in one command

Or run each step yourself (the explicit path make dev automates):

make setup
make db                      # local Postgres + pgvector (docker compose)
# terminal 1 — backend (local mode = zero-login; multi-tenancy runs as tenant #1)
PERSONALAI_DEFAULT_MODEL=qwen3:14b make run-backend
# terminal 2 — UI -> http://localhost:5173 (no token needed in local mode)
pnpm --filter @personalai/ui dev

Requires a local Ollama with a model pulled. app_mode defaults to local (zero-login dev). For multi-tenant hosted mode (real login + cookies + CSRF) set PERSONALAI_APP_MODE=hosted. Full guide: docs/guides/local-chat.md; all env vars are in .env.example.

---

Principles

Principle	Meaning
Local-first, cloud-optional	Full core works offline; any egress is opt-in, per-provider, and visible.
Structured-output-first	All agent ↔ backend ↔ tool ↔ UI messages are schema-validated.
Zero-trust I/O	Files, prompts, model outputs, tool results, and MCP servers are treated as adversarial.
Least privilege + explicit consent	Tools are off by default; grants are narrow, scoped, and revocable.
Verified provenance	Every dependency has a known reputable maintainer, license, maturity, and a documented reason.
Portability	Swap local ↔ remote models and storage backends behind stable interfaces.
Auditable & reproducible	Append-only audit log, SBOM, signed releases, reproducible builds where feasible.

---

How it works

A single-host modular monolith (hexagonal: ports & adapters + registries) fronting isolated runtimes — local model servers and sandboxed tools/MCP servers — with security, audit, and tenant isolation as cross-cutting layers.

The AI workflow. Every turn runs in one of two modes, chosen per tenant:

• Single-agent loop — one model reasons and calls tools through the gateway until it answers.
• Multi-agent graph (LangGraph, ADR-0012) — planner → researcher → critic (with an optional tool-armed verifier): the planner can fan out over multiple retrieval sources (fused with cross-source RRF), a judge fact-checks the answer against independently-gathered evidence (retrieval + a bounded tool re-check), and a bounded evaluator-optimizer loop can re-plan or revise.

Both modes share the same security seams:

• Tool/MCP gateway — permissions, schema-validated I/O, risk approval, an egress allowlist, and an append-only audit log front every tool and MCP server.
• Two durable human-in-the-loop gates — an answer-approval gate and a blocking egress-approval gate (ADR-0013) that pause the run durably when a tool reaches a non-allowlisted host (allow-once / allow-always / deny / inspect).
• RAG + memory — pgvector hybrid retrieval over your ingested documents (with citations) plus per-chat short-term and cross-chat long-term memory feed the prompt each turn. Documents arrive via uploads or continuously-synced local folders (on-device OCR for scans), and a knowledge graph of their entities is built alongside the vector index. See Documents & folders.

Full diagram and rationale: architecture report.

Stack

Area	Choice
Backend	Python (uv workspace) + FastAPI, hexagonal modular monolith
UI	React + Vite SPA (Tauri shell for desktop)
Database / RAG	PostgreSQL + pgvector
Model providers	Ollama (local, default) and OpenAI-compatible (remote, opt-in)
Model suite	Chat qwen3.6, embeddings qwen3-embedding, NER qwen3:14b, STT faster-whisper — see model suite
Agent orchestration	Single-agent loop + opt-in LangGraph multi-agent graph (ADR-0012)
Auth / multi-tenancy	argon2id + server sessions + Postgres Row-Level Security (ADR-0010)
Schemas	Pydantic / Zod + JSON Schema

The complete provenance register (maintainer, license, what each adopted dependency is used for) lives in SUPPLY-CHAIN.md. The modular design and extension seams are described in the architecture report's §22 modular seams.

---

Documentation

Guides (how to use it):

Guide	Purpose
Local chat	Run streaming chat over local Ollama models.
Remote providers	Use a remote OpenAI-compatible provider (opt-in).
Files + RAG	Chat with your documents (ingestion → pgvector RAG).
Documents & folders	Continuously-synced folders, on-device OCR, and the entity knowledge graph.
Memory	Short-term and long-term memory (view/edit/erase).
Tools	Built-in tools and the gateway.
Agent loop	Single- and multi-agent modes.
MCP servers	Plug in / manage MCP servers.
Settings	Per-tenant settings (model, agent, egress, timeout).

Project & architecture:

Doc	Purpose
Architecture report	The full architecture: principles, components, runtime, security, and the modular seams.
Model suite	The layered model stack and what each model is for.
Data extraction pipeline	How documents are parsed, OCR'd, chunked, embedded, and turned into a knowledge graph.
Context assembly	How prompt context is built (first vs follow-up questions).
ADRs	Architecture Decision Records.
Threat model	Trust boundaries and threats (v1).
Security policy	Reporting and security posture.
Dependency policy	Provenance, verification, SBOM, scanning rules.
Supply-chain register	Living inventory of every adopted dependency + creator.
Onboarding / dev guide	How to work in this repo.
Remote A100 dev VM	Provision/sync/teardown an Azure A100 GPU dev VM (Terraform + ops scripts in infra/).
Releasing & versioning	Version source of truth, release & signing.
Contributing	GitHub flow, branching, commits, PRs.
Changelog	Per-release history and the versioning policy.

---

Contributing & workflow

This repo uses GitHub flow: main is protected; all work happens on short-lived feature branches merged via pull request. See CONTRIBUTING.md.

---

License

Apache-2.0 © 2026 Lucian Hanga.