My personal AI assistant. Built as a personal project.
MAX is my long-term project to build a personal, voice-first AI assistant that works across my devices, understands what I want to accomplish, and helps me carry out tasks safely and reliably.
I'm designing MAX as my own assistant and software stack: its identity, experience, orchestration, memory, permissions, task execution, and skill system are defined by this project. I may use established libraries or external integrations where they are genuinely necessary, but they are implementation details—not MAX's identity.
Status (2026-11-05): Foundation and architecture documents are merged, along with five owner-merged local-development milestones (Core, durable tasks, dual-format Gateway, limited Trust/verification, and a local read-only task timeline). Milestone 6 adds a lifecycle CLI on a separate owner-review branch. MAX is not yet an autonomous assistant, connected AI model, desktop/mobile client or production service. Features below remain goals unless explicitly marked implemented.
- Be present when I need it. A floating cyan-and-blue holographic orb on my desktop, with clear listening, thinking, speaking, and working states.
- Talk naturally. Wake-word or push-to-talk interaction, responsive speech, interruptions, and an original refined British-English voice.
- Help me get things done. Plan work, use approved tools, coordinate specialized agents, save progress, and show evidence of what actually happened.
- Remember the right things. Keep useful personal preferences, project context, and task history while letting me review, correct, export, or delete them.
- Improve over time. Evaluate outcomes, learn from corrections, and safely add or refine skills without silently changing its permissions.
- Work across my devices. Windows 11 and Arch Linux/Hyprland desktop companions, with an iPhone browser interface.
- Respect my boundaries. Ask before consequential actions, protect sensitive information, and never mistake a model's suggestion for permission.
I'm organizing MAX around a set of modules I control:
| Module | Responsibility |
|---|---|
| MAX Core | Understand goals, plan tasks, coordinate workers |
| MAX Gateway | Route requests through a model-independent interface |
| MAX Trust | Enforce permissions, approvals, and audit rules |
| MAX Memory | Store and retrieve useful context with provenance |
| MAX Skills | Inspect, test, register, and roll back capabilities |
| MAX Voice | Handle speech, wake-up, and interruption |
| MAX Presence | Render the desktop companion and mobile interface |
| MAX Nodes | Execute authorized work on enrolled devices |
| MAX Evolution | Evaluate improvements and support bounded recovery |
| MAX Connect | Connect optional personal services and communication channels |
These are logical parts of one personal project, not a claim that ten standalone services already exist. The architecture is designed to keep the core independent of any one AI provider or third-party framework.
I want MAX to be dependable before it becomes complicated. My development approach is to design the security boundaries first, implement small working pieces, test real outcomes, and only then expand the system.
MAX will never be allowed to grant itself permissions, treat external content as trusted instructions, or report an action as complete without evidence. Sensitive operations require explicit confirmation. Payment authentication secrets do not belong in assistant memory.
I have an internal local-development Python/FastAPI Core, not a publicly hosted assistant. The local CLI binds to 127.0.0.1 and uses a strong but temporary single-owner bootstrap token, which is not adequate for remote or high-risk authorization.
| Completed review milestone | What is actually in the repository | What is not yet delivered |
|---|---|---|
| 1 — Core bootstrap | Local auth/config/health API, redacted access logs and CI | Production accounts, multi-device sessions or app UI |
| 2 — Durable tasks | PostgreSQL/Alembic task store, idempotency, cancellation, checkpoint/lease and internal outbox methods | Actual task worker, external effect dispatcher or backup proof |
| 3 — Model Gateway | Mock-tested OpenAI Chat Completions and Anthropic Messages text adapters, streaming, privacy and admission cost checks | Connected FreeLLMAPI/provider account, exact billing/quotas, real model output |
| 4 — MAX Trust | Only one allowed read-only task.status capability, task/actor/session/device-bound owner approvals, single-use ledger and fixture-based independent verification |
Real external observer, MFA, production authorization or consequential tools |
| 5 — Task timeline | Signed, owner-bound, read-only paginated task event history and local terminal viewer | Task workers, real-world activity or production client |
Historically verified CI for merged PR #7 reported 125 passing tests on Python 3.11 and 125 on 3.13, with an ephemeral PostgreSQL database. This does not verify any live provider, actual device or real-world action. My setup and boundaries are in Core setup, task persistence, gateway implementation and Trust implementation.
The Milestone 5 local read-only timeline is now merged. A separate review-only Milestone 6 adds interactive local task lifecycle commands: create a non-sensitive development task with a replay key, retrieve state, reuse the timeline, request cancellation, then read recorded state again. It adds no autonomous agent, worker or real-world execution.
The Phase 0 current-state audit, 53-row requirements matrix and architecture exit criteria distinguish plans from evidence. Payments, deployment, shell actions, document sharing and remote computer control remain unavailable. This CLI must still pass CI and owner review before merge.
| Platform | Experience |
|---|---|
| Windows 11 | Floating desktop orb, background voice, gaming-aware quiet mode |
| Arch Linux + Hyprland | Desktop companion and authorized local execution |
| iPhone | Responsive private web companion |
Platform-specific behavior will be validated on real devices. In particular, Wayland overlay behavior and mobile background voice are not assumed to work without testing.
- Architecture
- Product specification
- Technical design
- Security architecture
- Roadmap
- Implementation plan
- Research and technology evaluation
- Architecture diagrams
- Phase 0 current-state audit
- Requirement-to-code traceability
- Architecture exit criteria
The MAX identity, personality, and operating model describe how I want the assistant to behave. AGENTS.md contains separate instructions for coding workers; the future runtime must enforce security in code rather than relying on Markdown alone.
MAX is a personal project. I'm building it for myself, one verified capability at a time.
I'm adding my first manually invoked, strictly allowlisted local task execution in a separate review-only milestone. The only operations are a constant static status response and bounded integer addition, using typed JSON data. The worker uses PostgreSQL leases and checkpoints, can acknowledge a cancellation only after its operation stops, quarantines interrupted/uncertain tasks and records outcomes as awaiting independent verification, not completed. No model, general code execution, shell, network tool, personal-file access, or agent orchestration is enabled. See bounded worker limits and local test commands. This work is not merged or deployed unless I review and approve its PR.
I can now manually ask a separate trusted, local arithmetic observer to recompute the expected answer for a previously executed, non-sensitive dev.add task. Unlike the bounded worker, this observer independently reads the persisted input, recomputes the mathematical answer, and asks the existing IndependentVerifier to record a provenance-bound, idempotent verdict. A supported result may complete the task; mismatches and unavailable evidence do not. This proves mathematical-answer correctness, not that the original worker actually ran or that any external effect occurred. It adds no model, browser, shell, unrestricted files, remote listener or deployment. See independent evidence observer for commands, constraints and migration precautions. This is review-only until the owner merges the separate PR.
A new MCP discovery library initializes explicitly configured HTTPS MCP servers and lists bounded tool metadata using the official Python SDK. Multiple servers keep separate identities. Discovery does not grant permission to execute a tool. Plugin installation and the personal PC workflow (wake, isolated coding, PR/CI verification, safe shutdown and reporting) remain unimplemented; their implementation sequence and device prerequisites are in the milestone document. No live MCP account or personal device was accessed.
An additional cloud-to-local fallback trial can reuse the existing gateway with a separately owner-verified OpenAI-compatible loopback model. Safe failover covers cloud 429/503 and definite connection-establishment errors only. It does not infer real locality from a proxy URL, install models, execute tools or make MAX autonomous. Real-device smoke tests and owner approval remain required.
A separate provenance-first memory foundation introduces SQL-backed pending suggestions, explicit owner approval, confidence decay and hard erasure. This is library-level work only: there is no automatic learning, graph/vector search, user-facing memory interface or deployed production database. Cloud/local model connections and MCP tool execution remain separate, unverified security gates.