Skip to content
Flanxiyum001Public

About

Flanxiyum's Personal AI Assistant

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

MAX

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.

What I want MAX to do

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

The MAX architecture

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.

How I'm building it

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.

Current implementation — merged milestones #1–#4

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.

Planned platforms

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.

Project documentation

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.

Milestone 7 — bounded local developer worker (review branch)

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.

Milestone 8 — independent dev.add evidence observer (owner-review branch)

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.

Milestone 10 — MCP connections (review branch)

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.

Milestone 13 — opt-in safe cloud-to-local text trial (review branch)

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.

Milestone 12 — reviewed memory records (owner-review branch)

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.

About

Flanxiyum's Personal AI Assistant

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages