Multi-User Support

Every user gets isolated memory, credentials, and sessions. This deep dive explains the internals of user isolation and how to build multi-tenant applications.

Overview

MUXI isolates users through:

1. User ID - Identity header
2. Sessions - Conversation contexts
3. Memory Isolation - Per-user storage

User Identification

Pass user ID in header:

curl -X POST http://localhost:7890/api/my-assistant/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-Muxi-Client-Key: fmc_..." \
  -H "X-Muxi-User-Id: user_123" \
  -d '{"message": "Hello"}'

Default user ID: "0" (single-user mode)

Session Management

Start a Session

curl -X POST http://localhost:7890/api/my-assistant/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-Muxi-Client-Key: fmc_..." \
  -H "X-Muxi-User-Id: user_123" \
  -d '{"message": "Hello"}'

The response contains the generated session_id. Pass it on later requests to continue the same conversation:

curl -X POST http://localhost:7890/api/my-assistant/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-Muxi-Client-Key: fmc_..." \
  -H "X-Muxi-User-Id: user_123" \
  -d '{"message": "Hello", "session_id": "sess_abc123"}'

Get Session History

curl http://localhost:7890/api/my-assistant/v1/sessions/sess_abc123 \
  -H "X-Muxi-Client-Key: fmc_..." \
  -H "X-Muxi-User-Id: user_123"

Memory Isolation

Configuration

memory:
  persistent:
    enabled: true
    provider: postgresql
    connection_string: ${{ secrets.POSTGRES_URI }}
    user_isolation: true

How It Works

User A: "Remember I like Python"
         ↓
    Stored: user_a.preferences.python = true

User B: "What language do I like?"
         ↓
    Search: user_b.preferences (empty)
    Response: "I don't know your preference yet"

Database Schema

PostgreSQL with user isolation:

CREATE TABLE memories (
    id SERIAL PRIMARY KEY,
    user_id VARCHAR(255) NOT NULL,
    session_id VARCHAR(255),
    content TEXT,
    embedding VECTOR(1536),
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_user ON memories(user_id);

Session Lifecycle

Create Session
      ↓
Multiple Messages (same session)
      ↓
Session Expires (configurable)
      ↓
Memory Persists (if enabled)

Session Expiry

memory:
  session_timeout: 3600  # 1 hour

Multi-Tenant Architecture

For SaaS deployments:

Tenant A
├── User 1 → Isolated memory
├── User 2 → Isolated memory
└── User 3 → Isolated memory

Tenant B
├── User 1 → Isolated memory
└── User 2 → Isolated memory

Use compound user IDs:

X-Muxi-User-Id: tenant_a:user_1

Security

• Users cannot access other users' data
• Sessions bound to user ID
• No cross-user memory leakage
• API keys control access level

SDK Usage

response = formation.chat(
    {
        "message": "Hello",
        "session_id": "sess_user_123",
    },
    user_id="user_123",
)