Architecture Decision Records

We record non-trivial technical choices as ADRs in MADR format. They live in this folder, numbered sequentially, and never change status once accepted — instead, a new ADR supersedes the old one and links back.

Process

1. Discuss the idea in an issue using the ADR proposal template.
2. Run just adr-new "<short title>" to copy 0000-template.md to the next number.
3. Open a PR adding only the ADR. Get review. Set status to Accepted on merge (or Rejected, if appropriate — rejected ADRs still get merged so the reasoning isn't lost).
4. If the decision is later reversed, write a new ADR that supersedes the old one; update the old one's status to Superseded by ADR-NNNN.

ADRs are required before introducing application code in a new area (new module, new external dependency, new architectural pattern). Small fixes, refactors, tests, and doc-only changes do not need an ADR.

Index

#	Title	Status
0001	Record architecture decisions	Accepted
0002	License under PolyForm Noncommercial 1.0.0	Accepted
0003	Require a CLA for outside contributions	Accepted
0004	Conventional Commits + release-please	Accepted
0005	Python 3.11 as the primary runtime	Accepted
0006	Praetor on FastAPI + LangGraph	Accepted
0007	Home Assistant as the device control plane	Accepted
0008	Voice input via client-side transcription	Accepted
0009	NATS as the message bus	Accepted
0010	Hybrid memory: SQLite + vector store	Accepted
0011	Provider-agnostic LLM Gateway	Accepted
0012	Audit every brain decision	Accepted
0013	Policy engine guards real-world side effects	Accepted
0014	Trunk-based development with release branches as needed	Accepted
0015	Ruff + mypy + pytest as the Python toolchain	Accepted
0016	Repository and package layout	Accepted
0017	Configuration via pydantic-settings with layered sources	Accepted
0018	Structured logging with structlog	Accepted
0019	SQLite persistence via SQLAlchemy Core and Alembic	Accepted
0020	Episodic memory retention via time-based TTL	Accepted
0021	Dashboard: server-rendered HTMX, SSE, single-token auth	Accepted
0022	Backup and restore via SQLite Online Backup API	Accepted
0023	OpenTelemetry tracing as an opt-in extra	Accepted
0024	Documentation site on mkdocs-material + GitHub Pages	Accepted
0025	Lightweight security review as a living document	Accepted
0026	Multi-provider LLM gateway	Accepted
0027	NATS auth and multi-host Legion	Accepted
0028	Tools beyond HA: workers + generalised Policy Engine	Accepted
0029	Docker distribution + caesar init for 10-minute install	Accepted
0030	Proactivity: scheduled triggers and ntfy.sh notifications	Accepted
0031	HA event triggers: subscribe, match, fire the brain	Accepted
0032	Webhook triggers: third Trigger source variant	Accepted
0033	Personal facts: making CAESAR remember what you told it	Accepted
0034	Episodes and decay: making semantic recall actually useful	Accepted
0035	Legion plugin loader: out-of-tree workers via entry points	Accepted