Personal AI Architecture

Own your AI. An open blueprint for building personal AI systems you own. Keep your memory, swap everything else.

We will soon rely on personal AI systems in every area of our lives. We should own them, so they always work in our interest, and the wealth AI creates flows far and wide instead of to a few Big Tech platforms.

What this is

Not an app, and not a framework you install. A blueprint, plus a starter kit to build from.

• The specification (personal-ai-architecture-spec.md): what every PAA system must promise, including product stories, with known gaps tracked separately.
• The architecture (overview.md): how the system works, its principles, decisions, component specifications, and explanatory background.
• Contracts (contracts/): the exact OpenAPI and JSON Schema shapes code must match, plus canonical examples.
• Conformance (conformance/): language-neutral checks and review guidance that prove a system conforms.
• Outside adapters: D201 requires an owned adapter, including a pass-through, for each active outside provider, foreign client format and external tool source. Native Gateway API clients and owner-controlled internal boundaries need no extra adapter; ARCH-23 states the check.
• Language templates: starting points in TypeScript, Python, Go, Rust and Java. The v1.0 candidates pin PAA contract commit 47d6471 and pass the shared-validator and native checks. After release, use the v1.0 tag as the architecture source. See template readiness for exact template commits and limits. These checks prove named starter paths, not full product conformance.

Language templates

Language	Starter
TypeScript	ts-architecture-template
Python	python-architecture-template
Go	go-architecture-template
Rust	rust-architecture-template
Java	java-architecture-template

These are implementation starters, not qualified products. Each repository names the paths its tests exercise and the work needed for a complete deployment. Check its pin against PAA main before starting a new build.

For the rc.2 newcomer run, use TypeScript template commit b70ef42 and the PAA v1.0 tag. The contract pin is 47d6471. This candidate passed a controlled local Gateway-to-external-MCP call and the shared validator. Dave W's independent rerun of this candidate passed the six builder checks, the two rc.2 blocker checks, and the full verification suite. The earlier rc.1 independent retest remains historical evidence.

How it works

Four components and two APIs:

Part	What it does
Your Memory	All your data, in files you own. Everything else depends on it; it depends on nothing.
Agent Loop	Calls the model, runs the tools it asks for, and repeats until the job is done.
Gateway	One front door for every interface. Start on the web, pick up on your phone.
Auth	Controls who and what gets in. It checks every request and every tool call.
Gateway API	How interfaces connect. Anything that speaks it plugs in.
Model API	How models connect. Which model and provider to use is your preference; a failure never quietly switches either choice.

Start here

I want to...	Start here
Understand the architecture	Architecture overview
Look up an unfamiliar term	Decision glossary
Build from a tested starter	Choose a language template (current-main status)
Build with an AI coding agent	AGENT.md, the architecture and a language template
Build one component	Its architecture spec, contracts and conformance checks
See what every system must promise	Product spec
Check my system conforms	Conformance guide

To run this repository's Python contract and conformance checks, install the declared dependencies first. The conformance guide also provides a compatible dependency set for package indexes missing the primary pin.

python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -r requirements-ci.txt
python3 scripts/check-contracts.py
python3 conformance/runner.py

Built on PAA

BrainDrive is a personal AI assistant you own and control, built on all four PAA components by the team that wrote this architecture. Built something on PAA? Share it on the forum.

Contributing

We welcome pull requests for documentation, contracts and specification improvements. See CONTRIBUTING.md.

License

MIT. See LICENSE.