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