Maysii

Multi-channel AI Gateway — Connect your AI Agent to 28+ messaging platforms through a unified gateway.

Maysii is a Python rewrite of openclaw/openclaw, featuring MCP tool integration, 20+ built-in tools, cross-platform UI (Web/Desktop/Mobile), and an OpenAI-compatible HTTP API.

Documentation — Quick Start, Installation Guide, Configuration, Concepts, Troubleshooting.

Features

🎛 Agent Harness Architecture (v5.0)

Six-component production-grade agent runtime based on the Agent Harness Design Guide:

Plus Multi-Agent Orchestration (5 engines), Deep Research Engine, Event Bus, EncryptedText, Incremental Migrations, and Skills Self-Repair System.

🔌 Context Engine Plugins (v5.0)

Pluggable context management architecture — swap compression strategies without touching core code:

from maysii.agents.context.plugins import ContextEnginePluginRegistry, DagCompressorPlugin
registry = ContextEnginePluginRegistry.get_instance()
registry.register(DagCompressorPlugin(), set_default=True)

See Context Engine Plugin Guide for custom plugin development.

🧭 Agent Routing (v5.0)

Channel-aware agent routing with 7-tier priority matching and persistent thread bindings:

from maysii.routing import AgentRouter, RoutingRule
router = AgentRouter(default_agent_id="main")
router.register_rule(RoutingRule(channel_type="telegram", agent_id="telegram-bot"))
agent = router.match("telegram", sender_id="VIP123")  # → "telegram-bot"

🤖 Agent Runtime

• Multi-provider LLM streaming (OpenAI, Anthropic, Google Gemini, Ollama, and 25+ more)
• Provider resilience: dead-host cooldown, auto-fallback, shared connection pool, auto-detection
• Anthropic prompt caching with ephemeral markers — ~85% cache hit rate
• Reasoning model support: 7 thinking model patterns (Qwen3, DeepSeek-R1, DeepSeek-V3, etc.)
• 20+ built-in tools: file I/O, grep, find, exec, web search/fetch, browser, memory, cron, TTS
• MCP (Model Context Protocol) — stdio, HTTP, and Streamable HTTP transports + OAuth
• Docker sandbox for isolated tool execution (CPU/memory limits, network isolation)
• Task planner with multi-step Plan/Step decomposition
• Meta-Tool system: invoke_skill, invoke_channel, invoke_memory, invoke_mcp
• User interrupt system (cancel/append mid-generation)
• Sub-agent orchestration (spawn, steer, kill)
• SKILL.md-based skill injection
• Skills self-repair via SkillLearner teacher-escalation loop
• Deep Research engine — search→read→synthesize→report pipeline

🧠 Memory System

• Context compaction with LLM-based summarization
• Cross-session context recovery via ContextStore (SQLite-persisted)
• Hybrid search: SQLite FTS5 + LanceDB vector search
• Active memory with auto-recall and auto-capture hooks
• Daily summary service for session consolidation
• Wiki System (Claim/Evidence model with contradiction detection, GitLab-compatible)
• Dreaming System — 3-phase memory consolidation (LIGHT/DEEP/REM) with 6-dimensional scoring
• Recall cache with TTL-based session isolation

💬 28+ Messaging Channels

Telegram, Discord, Slack, WhatsApp, Signal, iMessage, Feishu/Lark, DingTalk, QQ, MS Teams, Matrix, IRC, LINE, Twitch, Nostr, X (Twitter), BlueBubbles, Google Chat, Mattermost, Nextcloud Talk, Synology Chat, Tlon/Urbit, Zalo, OneBot, Web Chat, Voice Call, and more.

Unified ChannelPlugin interface — each channel is a self-contained module with DM/group policy, allowFrom whitelists, mention gating, and agent routing.

🚪 Gateway

• FastAPI + WebSocket v3 bidirectional protocol
• OpenAI-compatible HTTP API (/v1/chat/completions, /v1/responses, /v1/models)
• 30+ RPC methods: chat, sessions, agents, channels, config, models, browser, cron, plan, backup, tools
• REST API for auth, devices, webhooks, usage, logs, plans, cron, skills
• Config hot-reload, channel health monitoring
• MkDocs documentation site mounted on gateway

🖥 Cross-Platform UI

• Next.js 15 Web Application
• Tauri 2.x Desktop App — Rust shell wrapping the Web app (no native frontend; macOS, Linux, Windows)
• Expo React Native Mobile App (iOS, Android)
• 17+ pages: Chat, Agents, Channels, Sessions, Usage, Cron, Plans, Skills, Nodes, Voice, Logs, Debug, Config, System, Settings

🛡 Security

• Command exec approval rules
• Workspace sandbox boundary
• SSRF prevention
• Plaintext secret scanning
• Configuration security audit
• EncryptedText (SQLAlchemy TypeDecorator with Fernet encryption)
• Internal token authentication (loopback-only bypass)

Quick Start

Requirements

• Python >= 3.10
• An LLM API key (OpenAI, Anthropic, Google Gemini, Ollama, or any OpenAI-compatible provider)

Install

# One-line install (macOS / Linux)
curl -fsSL https://raw.githubusercontent.com/maythyai/maysii/master/scripts/install.sh | bash

# From PyPI (recommended)
pip install maysii

# Or via pipx (isolated environment)
pipx install maysii

# macOS via Homebrew
brew install maythyai/tap/maysii

# From source (development)
pip install -e ".[dev,ui]"

# Docker
docker run -it --rm -e OPENAI_API_KEY="sk-..." ghcr.io/maythyai/maysii:latest maysii agent "Hello"

Optional Extras

First Run

# 1. Interactive setup
maysii setup --wizard

# 2. Chat with the agent
maysii agent "What is the weather in Tokyo?"

# 3. Start the gateway
maysii gateway

# 4. Launch the desktop UI
maysii ui

# 5. Or launch as a web app
maysii ui --web --port 18776

CLI Reference

Setup & Run

Configuration

Agents & Routing

Channels & Messages

Auth, MCP & Devices

Sessions & Models

Security & System

Memory & Knowledge

Supported Channels

Supported LLM Providers

Core Providers

OpenAI-Compatible Providers

OpenRouter, Together AI, Groq, Fireworks AI, Perplexity, and 15+ more.

Chinese Providers

DeepSeek, Moonshot/Kimi, Zhipu/GLM, Qwen/DashScope, Volcengine/Doubao, MiniMax, Qianfan/ERNIE.

MCP (Model Context Protocol)

Connect external tool servers via MCP. Config format is compatible with Claude Desktop and Cursor.

Add to ~/.maysii/maysii.json:

{
  "tools": {
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
      },
      "remote-api": {
        "url": "https://example.com/mcp/",
        "transportType": "streamable-http",
        "headers": { "Authorization": "Bearer xxx" }
      }
    }
  }
}

Supports stdio, HTTP, and Streamable HTTP (SSE+POST) transports. Built-in MCP servers include Memory, RAG, and Image Generation.

Configuration

Maysii stores its state in ~/.maysii/:

~/.maysii/
├── maysii.json          # Main config (JSON5 with comments)
├── auth-profiles.json   # API keys and OAuth credentials
├── data/                # ContextStore, ThreadBindings, Webhooks (SQLite)
├── sessions/            # Agent session transcripts (JSONL)
└── workspace/           # Workspace files (AGENTS.md, HEARTBEAT.md, etc.)

Example Config

{
  "models": {
    "providers": {
      "openai": { "apiKey": "sk-..." },
      "anthropic": { "apiKey": "sk-ant-..." }
    }
  },
  "agents": {
    "defaults": { "model": "claude-sonnet-4-20250514", "provider": "anthropic" }
  },
  "channels": {
    "defaults": { "agentId": "main" },
    "telegram": { "token": "123:ABC", "agentId": "assistant" },
    "discord": { "token": "xyz" }
  },
  "auth": {
    "profiles": {
      "openai-work": { "provider": "openai", "apiKey": "${OPENAI_WORK_KEY}" }
    }
  },
  "context": {
    "engine": {
      "plugin": "dag-compressor",
      "compaction": { "maxTokens": 128000, "strategy": "dag" }
    }
  },
  "routing": {
    "rules": [
      { "channel": "telegram", "sender": "VIP123", "agent": "vip-assistant" }
    ]
  }
}

Environment Variables

Architecture

maysii/
├── src/maysii/              # Python backend (755+ files)
│   ├── agents/              # Agent runtime
│   │   ├── harness/         # Agent Harness 6-component (25 modules)
│   │   │   ├── loop.py              # E: ExecutionLoop
│   │   │   ├── tool_registry.py     # T: Tool Registry + ToolIndex
│   │   │   ├── context_manager.py   # C: Context Manager
│   │   │   ├── state_store.py       # S: State Store
│   │   │   ├── hooks.py             # L: Lifecycle Hooks
│   │   │   ├── evaluation.py        # V: Evaluation + VerifierSubAgent
│   │   │   └── verifier.py          # Independent task verification
│   │   ├── context/         # Context engines + plugins (v5.0)
│   │   │   ├── engine.py            # ContextEngine ABC
│   │   │   ├── engines/             # SummarizeEngine, TruncateEngine
│   │   │   └── plugins/             # ContextEnginePlugin ABC + Registry + DAG
│   │   └── multiagent/      # 5 engine implementations
│   │
│   ├── routing/             # Message routing (v5.0)
│   │   ├── router.py                # AgentRouter + RoutingRule
│   │   ├── thread_bindings.py       # ThreadBindingManager
│   │   ├── integration.py           # RouteAndBind + config-driven router
│   │   ├── bindings.py              # AgentBindings (7-tier priority)
│   │   └── dispatch.py              # MessageDispatcher
│   │
│   ├── channels/            # 28 messaging channels
│   │   ├── base.py                  # ChannelPlugin interface
│   │   └── ...                      # telegram/, discord/, slack/, signal/, x/, ...
│   │
│   ├── gateway/             # Gateway server (FastAPI + WebSocket v3)
│   ├── config/              # Pydantic configuration system
│   ├── memory/              # SQLite + LanceDB memory with ContextStore (v5.0)
│   ├── mcp/                 # MCP client (stdio + HTTP + Streamable HTTP + OAuth)
│   ├── security/            # Security: EncryptedText, audit, CSP
│   ├── cron/                # APScheduler + TaskChainRunner + WebhookTrigger
│   └── cli/                 # 30+ Typer commands
│
├── apps/                    # TypeScript clients
│   ├── web/                 # Next.js 15 Web app
│   ├── desktop/             # Tauri 2.x Desktop app
│   └── mobile/              # Expo React Native app
│
├── packages/                # Shared packages (types, API client, UI)
├── tests/                   # 6125 tests (6125 passed, 1 skipped)
└── docs/                    # MkDocs documentation

Tech Stack

Project Stats

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run specific test suites
pytest tests/maysii/routing/
pytest tests/maysii/agents/context/
pytest tests/maysii/channels/

# Type check (0 errors expected)
mypy --strict src/maysii/

# Lint & format
ruff check src/ tests/
ruff format src/ tests/

Contributing

Pull requests welcome. The project follows standard Python conventions:

• Code style enforced by ruff
• Type annotations enforced by mypy --strict
• Async-first architecture throughout
• All new features should include tests (80%+ coverage target)
• See CLAUDE.md for project conventions

Documentation

Acknowledgements

This project is inspired by Maysii (originally built with TypeScript). Maysii is a ground-up rewrite using Python + TypeScript, with additional features including context engine plugins, agent routing, DAG compression, and mypy strict enforcement.

Thanks to Next.js, Tauri, Expo, and the open-source AI community.

License

MIT — Copyright (c) 2026 CHEN SAI