Multi-User AI Bridge for MUDs
A bridge server that enables multiple simultaneous users to interact with an AI agent (Timmy) inside a persistent virtual world built on Evennia. Each user gets an isolated conversation context while sharing the same game environment — rooms, objects, and other players.
What It Is
Traditional AI chatbots operate in isolation: one user, one conversation, no shared world. This project embeds a sovereign AI agent inside a MUD (Multi-User Dungeon), solving three problems at once:
- Session isolation — each user has their own conversation history
- Shared environment — all users see the same rooms, objects, and each other
- Organic social interaction — users encounter the AI naturally within a game space
The bridge runs as an HTTP server alongside Evennia. Evennia commands call the bridge API to get the AI agent's responses.
Architecture
+-----------+ +-----------+ +-----------+
| User A | | User B | | User C |
| (telnet) | | (telnet) | | (telnet) |
+-----+-----+ +-----+-----+ +-----+-----+
| | |
v v v
+---------------------------------------------------+
| Evennia MUD |
| Rooms, Objects, Commands, World State (JSON) |
+------------------------+--------------------------+
|
v
+---------------------------------------------------+
| Multi-User Bridge (HTTP) |
| |
| SessionManager PresenceManager |
| +------------------+ +-----------------------+ |
| | Session A | | Room tracking | |
| | - user_id | | User enter/leave | |
| | - conversation | | Chat events | |
| | - AIAgent | +-----------------------+ |
| | | |
| | Session B | +-----------------------+ |
| | - user_id | | Crisis Protocol | |
| | - conversation | | - 988 Lifeline | |
| | - AIAgent | | - Crisis Text Line | |
| | | | - Grounding exercise | |
| | Session C | +-----------------------+ |
| | - ... | |
| +------------------+ |
+------------------------+--------------------------+
|
v
+---------------------------------------------------+
| Hermes Agent (AIAgent) |
| Model: xiaomi/mimo-v2-pro | Provider: nous |
| Tools: file, terminal |
| Per-session system prompt with world context |
+---------------------------------------------------+
API Reference
Health & Sessions
GET /bridge/health
Health check. Returns bridge status and active session count.
Response:
{
"status": "ok",
"active_sessions": 3,
"timestamp": "2026-04-12T20:30:00"
}
GET /bridge/sessions
List all active user sessions.
Response:
{
"sessions": [
{
"user": "Alice",
"room": "The Threshold",
"messages": 12,
"last_active": "2026-04-12T20:29:45",
"created": "2026-04-12T20:15:00"
}
]
}
Room & Presence
GET /bridge/world/<room_name>
Get world state data for a specific room.
Response:
{
"room": "The Threshold",
"data": {
"desc_base": "A quiet room with a green LED on the wall.",
"visitor_history": ["Alice", "Bob"]
}
}
GET /bridge/room/<room_name>/players
List players currently in a room.
Response:
{
"room": "The Threshold",
"players": [
{"user_id": "alice_01", "username": "Alice"},
{"user_id": "bob_02", "username": "Bob"}
]
}
GET /bridge/room/<room_name>/events[?since=<timestamp>]
Get recent room events (presence + chat). Optionally filter by timestamp.
Response:
{
"room": "The Threshold",
"events": [
{
"type": "presence",
"event": "enter",
"user_id": "alice_01",
"username": "Alice",
"room": "The Threshold",
"timestamp": "2026-04-12T20:15:00"
},
{
"type": "say",
"event": "message",
"user_id": "alice_01",
"username": "Alice",
"room": "The Threshold",
"message": "Hello everyone!",
"timestamp": "2026-04-12T20:15:30"
}
]
}
Chat & Actions
POST /bridge/chat
Send a message to Timmy. Creates or retrieves a per-user session with isolated conversation context.
Request:
{
"user_id": "alice_01",
"username": "Alice",
"message": "What do you see in this room?",
"room": "The Threshold"
}
Response:
{
"response": "I see bare stone walls and a single green LED pulsing softly.",
"user": "Alice",
"room": "The Threshold",
"session_messages": 5
}
POST /bridge/say
Say something visible to all players in the room (not directed at Timmy).
Request:
{
"user_id": "alice_01",
"username": "Alice",
"message": "Anyone else here?",
"room": "The Threshold"
}
Response:
{
"ok": true,
"event": {
"type": "say",
"event": "message",
"user_id": "alice_01",
"username": "Alice",
"room": "The Threshold",
"message": "Anyone else here?",
"timestamp": "2026-04-12T20:20:00"
},
"recipients": [
{"user_id": "bob_02", "username": "Bob"}
]
}
POST /bridge/move
Move a user to a new room. Triggers leave/enter presence events.
Request:
{
"user_id": "alice_01",
"room": "The Garden"
}
Response:
{
"ok": true,
"room": "The Garden",
"events": [
{
"type": "presence",
"event": "leave",
"user_id": "alice_01",
"username": "Alice",
"room": "The Threshold",
"timestamp": "2026-04-12T20:22:00"
},
{
"type": "presence",
"event": "enter",
"user_id": "alice_01",
"username": "Alice",
"room": "The Garden",
"timestamp": "2026-04-12T20:22:00"
}
]
}
Quick Start
Prerequisites
- Python 3.10+
- Evennia installed and configured
- Hermes Agent available at
~/.hermes/hermes-agent
1. Start the Bridge
cd /tmp/mud-bridge
python multi_user_bridge.py
The bridge starts on 127.0.0.1:4004 by default.
2. Configure Evennia
The Evennia command handler (timmy_commands.py) calls the bridge API. Set the bridge URL in your Evennia config:
TIMMY_BRIDGE_HOST = os.environ.get('TIMMY_BRIDGE_HOST', '127.0.0.1')
TIMMY_BRIDGE_PORT = int(os.environ.get('TIMMY_BRIDGE_PORT', 4004))
3. Connect
Telnet to your Evennia server and use the talk command to chat with Timmy:
> talk Hello, Timmy!
Timmy: The green LED pulses. "Hello. Welcome to The Tower."
4. Test the API
# Health check
curl http://127.0.0.1:4004/bridge/health
# Chat with Timmy
curl -X POST http://127.0.0.1:4004/bridge/chat \
-H 'Content-Type: application/json' \
-d '{"user_id":"test","username":"Tester","message":"Hello!","room":"The Threshold"}'
# Check who's in a room
curl http://127.0.0.1:4004/bridge/room/The%20Threshold/players
Crisis Protocol
Timmy is designed with crisis intervention in mind. If a user expresses crisis signals (suicide, self-harm, hopelessness, desperation), the agent immediately responds with ALL of the following in the very first reply:
- "Are you safe right now?" — always asked first
- 988 Suicide & Crisis Lifeline — call or text 988 (US)
- Crisis Text Line — text HOME to 741741
- Grounding exercise — Name 5 things you see, 4 you can touch, 3 you hear, 2 you smell, 1 you taste
The crisis protocol is embedded in the system prompt for every session. The agent never computes the value of a human life. It is present. It is in the room.
Configuration
| Variable | Default | Description |
|---|---|---|
TIMMY_BRIDGE_PORT |
4004 |
Bridge HTTP server port |
TIMMY_BRIDGE_HOST |
127.0.0.1 |
Bridge bind address |
HERMES_PATH |
~/.hermes/hermes-agent |
Path to Hermes Agent runtime |
WORLD_DIR |
~/.timmy/evennia/timmy_world |
Evennia world data directory |
Session Management
- Max sessions: 20 concurrent users
- Session timeout: 3600 seconds (1 hour) of inactivity
- Eviction policy: Least recently active session is evicted when at capacity
- Room events: Last 50 events per room are retained
Paper
This project accompanies the paper:
"Sovereign in the Room: Multi-User AI Interaction in Persistent Virtual Worlds"
We present an architecture for deploying sovereign AI agents as persistent, multi-user NPCs in text-based virtual worlds (MUDs), enabling isolated crisis-aware conversations within a shared environment, and demonstrate its application to suicide prevention through the Tower — a virtual safe space.
See paper/autoreason-mud-paper.md for the full draft.
License
This is a research project. See the paper directory for experiment data and methodology.