Technical Architecture
Seven layers. One graph.
Deterministic where correctness matters. LLM where judgement matters. Everything runs on a device you own, grounded in a local knowledge graph. Only prompts leave the premises.
Maxy sits at the orchestration layer of the agent stack — above the model, above the harness, below managed cloud infrastructure. It is built for business operations, not development workflows. A plugin architecture scopes tool access per session, a graph-backed memory model grounds every response, and a hard split between admin and public agents enforces data boundaries by design. It runs on commodity hardware with zero cloud dependency.
How the layers work together
Layer 1 — The device
A Raspberry Pi or Mini PC running Linux on your premises. This is the system boundary. Your data does not leave the device. Only LLM prompts and responses traverse external connections to Anthropic's API. Everything else — the graph, the agents, the workflows, the plugins — runs locally.
Layer 2 — Ontological substrate
Neo4j graph database and vector embeddings form the ontological substrate. This is not a data store bolted onto an LLM — it is the ground truth the entire system reasons against. Entity relationships, business rules, customer history, document knowledge, and agent memory all live here. Vector embeddings enable semantic retrieval; graph relationships enable context traversal. Neither alone is sufficient.
Layer 3 — Intelligence
The intelligence layer is where ontological grounding meets LLM reasoning. Claude (via the Anthropic API) handles language understanding and generation. Maxy handles everything else: resolving the relevant knowledge scope from the graph, filtering available tools to the resolved domain, assembling grounded context, and routing responses. LLM reasoning is applied only where it adds genuine value — interpretation, synthesis, judgement. Retrieval, routing, and execution are deterministic.
Layer 4 — Plugins & capabilities
The plugin manifest is Maxy's domain ontology. It defines which tools belong to which domain, which skills are available to which agent, and which capabilities are active for the account. When a request arrives, the agent does not scan all available tools — it resolves the relevant domain from the manifest and operates within that boundary. This is ontology-constrained tool discovery: the model cannot invoke a tool outside its resolved domain.
Layer 5 — Execution
Projects are first-class graph entities with dedicated tools that operate atomically — a single call provisions the project node, all child work items, dependency links, and stakeholder relationships in one transaction. The design is grounded in PMBOK 7th Edition and APM Body of Knowledge 5th Edition, adapted for conversational use: lifecycle phases track progression from planning through completion, server-side health signals surface blockers and overdue items as structured data, and three execution tiers (quick, standard, full) match operational complexity to the work at hand.
Tasks and Workflows complete the execution layer. Dependency tracking (BLOCKS relationships) and conflict detection (AFFECTS relationships) are graph-native — task sequencing and workflow steps follow graph-defined rules, not model discretion.
Layer 6 — Agents
Three agent tiers with formally separated access: Admin (owner-facing, full graph access, full tool access), Public (customer-facing, scoped to public knowledge only), and Specialist sub-agents (domain-specific execution dispatched by the admin agent). Each tier is a Role in the ontological sense — defined capabilities, defined knowledge access, defined interaction boundaries. Agents cannot escalate their own permissions.
Layer 7 — Interfaces
WhatsApp, Web Chat, Telegram, Email. All channels share the same underlying graph. A customer conversation on WhatsApp and a task created via the web interface exist in the same knowledge space. Channel is irrelevant; context is always whole.
Key Design Principles
Determinism where correctness matters
Tool routing, data access, workflow sequencing, and capability boundaries follow formal rules. The model cannot override them.
LLM reasoning where judgement matters
Language understanding, synthesis, and contextual response generation are handled by Claude — applied to grounded, locally-held data.
The graph as ontological substrate
Every entity and relationship lives in Neo4j. Agent reasoning is grounded against this at runtime, not assembled from parametric model knowledge. This is why Maxy performs well in domain-specific contexts where general LLMs are weakest.
Scoped knowledge, not open access
Public agents see public knowledge. Admin agents see everything. Documents, conversations, and contacts are scoped at write time. No agent can retrieve data outside its defined scope.
Privacy by architecture
On-premises deployment is not a feature — it is a structural guarantee. The device boundary is the privacy boundary.
This places Maxy at L2–L3 of the neurosymbolic coupling maturity model (Tuan, 2026): ontology-constrained tool discovery and knowledge-grounded reasoning, rather than the prompt-injection approach common in competing architectures.
Security & Data Protection
Inbound message screening
Every inbound message — regardless of channel — passes through a centralised screening gateway before reaching the agent. The gateway detects prompt injection patterns, classifies intent, and assigns a safety verdict. Unsafe messages on public channels are refused without agent invocation. Admin messages receive advisory screening only — flagged, never blocked.
Agent action audit trail
Every tool invocation by the admin agent produces a durable audit record in the knowledge graph — tool name, input, output, timestamp, and originating conversation. Records persist indefinitely and are queryable in conversation. This is not a debug log — it is a first-class data structure designed for accountability and operational review.
GDPR compliance by architecture
Data subject rights are exercised through the same conversational interface used for everything else. Subject access requests (Article 15) produce a portable export of all data held on a contact. Erasure requests (Article 17) perform a full cascade deletion across all data stores with a confirmation gate and deletion receipt. On-premises deployment means the data controller is also the data processor — no third-party data sharing.