How MUXI Works

You completed the quickstart. Here's what you actually built:

---
config:
  layout: elk
  elk:
    mergeEdges: true
    nodePlacementStrategy: LINEAR_SEGMENTS
---
flowchart TB
    Request(["Your Request
“Hello, assistant!”"])
    Server["MUXI Server :7890
Routes requests / Manages formations / Handles auth"]
    Overlord["Overlord
Loads memory context / Routes to agents / Applies soul / Updates memory"]
    A1["Agent"] & A2["Agent"] & A3["Agent"]
    LLM["LLM
(OpenAI)"] & Tools["Tools
(MCP)"] & RAG["Knowledge
(RAG)"]
    Response(["Response"])

    Request --> Server
    Server --> Overlord
    Overlord --> A1 & A2 & A3
    A1 & A2 & A3 --> LLM & Tools & RAG
    LLM & Tools & RAG --> Response

---
config:
  layout: elk
  elk:
    mergeEdges: true
    nodePlacementStrategy: LINEAR_SEGMENTS
---
flowchart TB
    Request(["<strong>Your Request</strong>
<small>“Hello, assistant!”</small>"])
    Server["<strong>MUXI Server :7890</strong>
<small>Routes requests / Manages formations / Handles auth</small>"]
    Overlord["<strong>Overlord</strong>
<small>Loads memory context / Routes to agents / Applies soul / Updates memory</small>"]
    A1["Agent"] & A2["Agent"] & A3["Agent"]
    LLM["LLM
(OpenAI)"] & Tools["Tools
(MCP)"] & RAG["Knowledge
(RAG)"]
    Response(["Response"])

    Request --> Server
    Server --> Overlord
    Overlord --> A1 & A2 & A3
    A1 & A2 & A3 --> LLM & Tools & RAG
    LLM & Tools & RAG --> Response

Think of it as:

• Server = Traffic controller (like Nginx for AI)
• Formation = Your complete AI system (like a Docker container)
• Overlord = The brain that manages memory, routes requests, and applies soul
• Agent = A specialized worker that uses tools and knowledge to complete tasks

What happens when you send a message

1. Your app sends a request

   curl -X POST http://localhost:7890/draft/my-assistant/v1/chat \
     -H "Content-Type: application/json" \
     -H "X-Muxi-Client-Key: YOUR_CLIENT_KEY" \
     -H "X-Muxi-User-Id: user_123" \
     -d '{"message": "What can you help me with?"}'

   The request hits your formation's API and goes to the Overlord. You can also connect via MCP from Claude Desktop, Cursor, or any MCP client -- the flow is the same. See Connect via MCP.

2. The Overlord builds context

   The Overlord assembles request context from the memory platform's context plane:

   • Buffer memory - Recent conversation messages
   • Long-term memory - User preferences and history (if enabled)
   • User Synopsis - Who the user is (derived from persistent memory)
   • Working memory - Current session state

   This context is attached to your message before any agent sees it.

3. The Overlord routes to an agent

   The Overlord decides how to handle your request:

   1. SOP match? → Execute the standard procedure
   2. Complex request? → Decompose into multi-agent workflow
   3. Simple request? → Route to the best-suited agent

   User:  "What can you help me with?"
     ↓
   Overlord: "Simple question → route to 'assistant' agent"

4. The agent processes with tools

   The selected agent:

   • Receives the message + context from the Overlord
   • Calls MCP tools if needed (web search, databases, etc.)
   • Activates skills on demand (loads instructions, runs scripts)
   • Retrieves relevant knowledge (RAG)
   • Sends everything to the LLM

5. The Overlord applies soul and responds

   The Overlord:

   • Applies the configured soul (tone, style) to the response
   • Streams the response back to your app
   • Records the conversation through the memory platform

The four things you configure

Every formation has four core building blocks. You don't need all of them - start simple and add as needed.

# agents/assistant.afs
id: assistant
name: My Assistant
system_message: You are a helpful assistant.

# mcp/web-search.afs
id: web-search
server: "@anthropic/web-search"

# formation.afs
memory:
  persistent:
    enabled: true

# agents/support.afs
knowledge:
  sources:
    - path: ./docs

Formation file structure

When you ran muxi new formation, you got this structure:

my-assistant/
├── formation.afs      # Main configuration (LLM, memory, defaults)
├── agents/            # Agent definitions (listed in formation manifest)
│   └── assistant.afs  # Your agent
├── mcp/               # Tool configurations (optional)
├── skills/            # Skill packages (optional)
├── knowledge/         # Documents for RAG (optional)
├── sops/              # Standard procedures (optional)
├── triggers/          # Webhook templates (optional)
└── secrets.example    # Required API keys template

The key files

schema: "1.0.0"
id: my-assistant

llm:
  models:
    - text: "openai/gpt-4o"

memory:
  persistent:
    enabled: true

schema: "1.0.0"
id: assistant
name: Helpful Assistant
description: General-purpose assistant

system_message: |
  You are a helpful assistant. Be concise and friendly.

# Optional: agent-specific tools
mcp_servers:
  - web-search

# Optional: agent-specific knowledge
knowledge:
  sources:
    - path: ./docs/faq.md

schema: "1.0.0"
id: web-search
server: "@anthropic/web-search"

# Some tools need API keys
env:
  API_KEY: ${{ secrets.SEARCH_API_KEY }}

Single agent vs. multi-agent

Single agent (what you built)

Simple formations have one agent that handles everything:

User → Overlord → assistant → LLM → Response

Good for: chatbots, simple assistants, focused tools.

Multi-agent (when you're ready)

Complex formations have specialized agents that collaborate:

User → Overlord ─┬→ researcher → find information
                 ├→ analyst    → analyze data
                 └→ writer     → draft response

The Overlord routes requests to the right agent or coordinates multiple agents for complex tasks.

Good for: customer support systems, research assistants, content pipelines.

Build Multi-Agent Teams →

Development vs. production

Local development

muxi up
# Draft available at http://localhost:7890/draft/{formation-id}

Production deployment

muxi deploy
# Formation deployed at http://server:7890/api/my-assistant

Deploy to Production →

Next steps

Now that you understand how MUXI works, choose your path:

Go deeper

Architecture - Complete system architecture
Formation Schema - Full YAML specification
The Overlord - How orchestration works
Request Lifecycle - Every step of a request