Common Questions and Use-cases

In YAML. Create an .afs file (Agent Formation Schema) with your agent's name, role, LLM provider, and capabilities. No framework code required.

name: support-agent
agents:
  support:
    soul: "Helpful customer support specialist"
    provider: openai/gpt-4o
    tools: [search, ticket-system]
    knowledge: ./docs/

Learn more: Formation Schema | Quickstart

MUXI has a four-layer memory system:

1. Buffer - Recent messages (fast, in-memory)
2. Working - Session state and tool outputs (FAISSx vector store)
3. User Synopsis - Who the user is (LLM-synthesized profile)
4. Persistent - Long-term storage (Postgres for multi-tenancy, SQLite for single-user)

User Synopsis reduces token usage by 80%+ by replacing full history with a concise profile.

Note: Long-term memory requires either Postgres (multi-tenant) or SQLite (single-user).

Learn more: Memory System | Memory Internals | Add Memory

Via MCP (Model Context Protocol). MUXI supports 1,000+ pre-built tools: web search, databases, file systems, APIs, and more.

tools:
  - mcp: brave-search
  - mcp: postgres
  - mcp: slack

Tools are loaded efficiently - schemas indexed once, not dumped into every request.

Learn more: Tools & MCP | Add Tools

Agents self-heal. When a tool fails, agents analyze the error and take corrective action:

User:  "Create file at /reports/q4/summary.txt"
Agent: write_file(...) → Error: "Directory doesn't exist"
Agent: create_directory("/reports/q4") → Success
Agent: write_file(...) → Success!

The user never sees the error - the agent just handles it. This works for missing directories, authentication issues, rate limits, and more.

Learn more: Tools & MCP

Point agents at documents. MUXI indexes PDFs, Markdown, Word, Excel, images, and more. Each agent can have its own knowledge set.

agents:
  legal:
    knowledge: ./contracts/
  support:
    knowledge: ./help-docs/

Uses semantic search (meaning, not keywords) and incremental indexing (only re-indexes changed files).

Learn more: Knowledge & RAG | Add Knowledge

Yes - Standard Operating Procedures (SOPs). Create markdown files in sops/ that define step-by-step procedures:

<!-- sops/refund-request.md -->
---
type: sop
name: Refund Processing
mode: guide
tags: refund, customer, payment

## Steps

1. **Verify Purchase** - Look up order in system
2. **Check Policy** - Verify refund eligibility
3. **Process or Deny** - Issue refund or explain denial

When a user request matches an SOP (via semantic search), the agent follows that procedure. SOPs have highest routing priority.

Note: SOPs are predefined templates. Regular workflows are created dynamically by the Overlord for each request.

Learn more: SOPs | Create SOPs

Yes. When a request is ambiguous, agents can ask for clarification instead of guessing:

User:  "Book a flight"
Agent: "I'd be happy to help. Where are you flying to, and what dates work for you?"

Configure clarification behavior per agent - when to ask, what to ask, how many times.

Learn more: Clarifications

Yes - artifacts. Agents can create documents, images, code files, reports, and more:

User:  "Create a sales report for Q4"
Agent: "Here's your Q4 sales report" + [sales-report-q4.pdf]

Artifacts are returned alongside the response and can be downloaded or processed by your app.

Learn more: Artifacts

Yes, but only the Overlord has a soul. Users talk to MUXI (the Overlord), not individual agents - so the soul defines how MUXI communicates.

Create a SOUL.md file in your formation directory:

<!-- SOUL.md -->
You are a friendly, professional assistant.
Be concise but warm. Use simple language.
Never use jargon unless the user does first.

Individual agents have system prompts (instructions for task execution) and capabilities (metadata for routing) - but not souls.

Learn more: Overlord Soul | The Overlord

Yes - structured output. Define a schema and get validated JSON back:

agents:
  extractor:
    output_format:
      type: object
      properties:
        name: { type: string }
        email: { type: string }
        sentiment: { type: string, enum: [positive, neutral, negative] }

Response is guaranteed to match your schema.

Learn more: Structured Output

The Overlord orchestrates everything:

• Intelligent Routing - Requests go to the best agent automatically
• Task Decomposition - Complex requests broken into steps
• Agent-to-Agent (A2A) - Agents delegate to specialists across formations

You define agents with specialties; the Overlord figures out who handles what.

Learn more: The Overlord | Agents & Orchestration | How Orchestration Works

All of them. MUXI is LLM-agnostic:

• OpenAI (GPT-4o, GPT-4, etc.)
• Anthropic (Claude 3.5, Claude 3, etc.)
• Google (Gemini)
• Ollama (local models)
• Any OpenAI-compatible API

Different agents can use different providers in the same formation.

Learn more: LLM Providers | Formation Schema

Yes - multi-tenancy is built in. Each user gets:

• Isolated memory (no data leakage)
• Separate conversation history
• Their own API credentials for tools

One server, many users, complete isolation.

Learn more: Multi-Tenancy | Multi-Tenancy Deep Dive

Yes - multi-identity lets you link multiple identifiers to one user:

# Same user, different platforms
formation.associate_user_identifiers(
    identifiers=[
        "alice@email.com",          # Email
        "U12345ABC",                 # Slack ID
        "user_123"                   # Your internal ID
    ]
)

# Now they all share the same memory
formation.chat("Hi", user_id="alice@email.com")  # Same user
formation.chat("Hi", user_id="U12345ABC")        # Same user

User chats on Slack, email, or web - same context everywhere.

Learn more: Multi-Identity Users | SDKs

Yes - cross-session memory. Working memory spans sessions:

User:  "Remember when we discussed Japan last week?"
MUXI: "Yes! You mentioned a 2-week trip in March..."
↑ Found in working memory from previous session

Sessions are separate conversation threads, but memory flows across them. Users can reference past chats without specifying which session.

Learn more: Sessions | Memory System

One command:

muxi deploy

MUXI is a single binary - no dependencies, no Docker required (though Docker is supported). Supports GitOps workflows for PR-based deployments.

Learn more: Deploy to Production | Set Up CI/CD | Production Checklist

Built-in observability. Every agent action emits structured events:

• LLM calls (tokens, latency, cost)
• Tool usage
• Workflow steps
• Errors

Export to Datadog, Elastic, Splunk, OpenTelemetry, or webhooks - no sidecars needed.

Learn more: Observability | Observability Events | Set Up Monitoring

Yes - automatic topic tagging. Every request gets 1-5 semantic topic tags:

Request: "Debug the OAuth authentication flow"
Topics: ["debugging", "oauth", "authentication", "api"]

No extra LLM calls - topics are extracted during request analysis. Use topics for dashboards, filtering, trend analysis, and alerting.

Learn more: Observability

Yes. Enterprise resilience patterns are baked in:

• Circuit breakers for failing dependencies
• Retries with exponential backoff
• Graceful degradation
• LLM response caching to reduce load and latency
• Auto-restart for crashed formations

Learn more: Resilience | Security Model

Helpful messages, not cryptic errors. The resilience layer translates technical failures:

Traditional: "Error: 401 Unauthorized"

MUXI: "Unable to connect to Linear. Please check that your
      API token is configured correctly in settings."

Plus automatic context-aware handling:

• Rate limited? → "Waiting 30 seconds before retrying..."
• Timeout? → "The service is slow, retrying..."
• Partial failure? → Delivers what succeeded + explains what didn't

Users stay informed, not frustrated.

Several built-in features help:

• Semantic LLM Caching - Not just exact matches! Similar requests hit cache: "What's the weather?" ≈ "How's the weather today?" → Cache hit!

  Typical savings: 70%+ cost reduction

• User Synopsis Caching - Compress long conversation history (80%+ token reduction)
• Efficient tool loading - Tool schemas indexed once, not sent every request
• Model mixing - Use cheaper models for simple tasks, expensive ones for complex

Learn more: LLM Caching | Memory Internals

Yes - scheduled tasks. Cron-style or natural language:

triggers:
  daily-report:
    schedule: "0 9 * * *"    # Every day at 9am
    action: "Generate daily analytics summary"

  weekly-cleanup:
    schedule: "every monday at 6am"
    action: "Archive old conversations"

Learn more: Scheduled Tasks | Triggers & Webhooks

Use human-in-the-loop (HITL). Define which actions require approval:

agents:
  finance:
    approvals:
      - action: "process_refund"
        when: "amount > 1000"
        notify: "finance-team@company.com"

The agent pauses, notifies the approver, and continues only after approval.

Learn more: Human-in-the-Loop

Yes. MUXI supports:

• SSE (Server-Sent Events) - Stream tokens as the model thinks
• WebSockets - Bidirectional real-time communication

Perfect for chat UIs and live dashboards.

Learn more: Real-Time Streaming | Response Formats

Use async operations. Long tasks run in the background with status updates. Users aren't left waiting.

Learn more: Async Operations

Yes - triggers and webhooks:

• HTTP webhooks trigger agent actions
• Cron-style scheduled tasks
• Natural language scheduling ("remind me tomorrow")

Learn more: Triggers & Webhooks | Create Triggers

Encrypted at rest. API keys never stored in plain text. Per-user credentials supported - each user can store their own keys for tools.

Learn more: Secrets & Security

HMAC-signed requests between CLI, SDKs, and server. Plus complete user isolation - data never leaks between users.

Learn more: Authentication | Security Model

Yes - per-user credentials. Each user can store their own API keys for tools:

# User stores their own OpenAI key
client.set_user_secret("openai_api_key", "sk-...")

# Agent uses user's key for their requests
# Other users' requests use other keys (or formation default)

Great for platforms where users pay for their own LLM usage.

Learn more: User Credentials | Secrets & Security

muxi dev

Runs your formation locally with hot reload. Change your .afs file, see changes immediately.

Learn more: Quickstart | CLI Cheatsheet

Yes - Python, TypeScript, and Go:

from muxi import Muxi
client = Muxi()
response = client.chat("Hello!")

Learn more: Python SDK | TypeScript SDK | Go SDK

Yes. The embeddable runtime lets you run MUXI inside your application - no separate server process.

Learn more: Embed in Your App

Yes. Pull formations from the MUXI Registry:

muxi pull @acme/customer-support
muxi pull @acme/code-reviewer

Learn more: Registry | Examples

Yes. Publish to the registry:

muxi publish

Supports semantic versioning, private formations, and organization sharing.

Learn more: Publish Formations | Versioning

Yes. The core stack is always free and self-hostable. No paywalls, no feature restrictions, no bait-and-switch licensing.

• Server, Runtime, CLI, SDKs - all open source
• Self-host on your infrastructure forever
• No usage limits, no "free tier"

Learn more: Our creed

MUXI follows the standard open-source infrastructure model:

1. GitHub Sponsors - Supporting OSS development
2. Professional services - Priority support and deployment help for production teams

The core product stays free. Revenue comes from optional services, not from restricting features.

Get Support

You CAN:

• Use freely for internal projects, products, research
• Use freely for building platforms and commercial applications
• Build and sell products that use MUXI
• Deploy for clients and customers
• Self-host on your infrastructure

You CAN'T:

• Offer MUXI itself as a hosted service (that's it)

You're protected:

• Self-hosted - Runs on your infrastructure, not ours
• Open source - Fork and maintain the code yourself
• Portable formats - Formations are YAML, not proprietary
• Standard protocols - MCP and A2A work with other systems

MUXI is backed by VarOps LLC with a long-term commitment. Revenue comes from sustainable services, not VC burn rate.

Different layer of the stack:

LangChain helps you build agents in code. MUXI runs agents in production.