maysii 1.2.0

Multi-channel AI gateway with extensible messaging integrations

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:

Component	Module	Description
E Execution Loop	harness/loop.py	Observe-think-act cycle with dual-mode tool resolution, provider fallback, hard termination
T Tool Registry	harness/tool_registry.py	9-field ToolMetadata, JSON Schema validation, RBAC, RAG-powered ToolIndex, auto-indexing
C Context Manager	harness/context_manager.py	Hybrid injection, layered compression, token budget, Anthropic cache control
S State Store	harness/state_store.py	3-tier storage (Working/Session/Persistent), checkpoint/recovery, execution log
L Lifecycle Hooks	harness/hooks.py	6 hook points: permission, rate-limit, audit, danger-block, mask, policy
V Evaluation	harness/evaluation.py	Component eval, trajectory analysis, LLM-as-Judge, VerifierSubAgent

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:

Plugin	Strategy	Description
DefaultContextPlugin	summarize + truncate	LLM-powered summarization with structured templates, truncate fallback
DagCompressorPlugin	4-layer DAG	critical (keep) / important (summarize) / contextual (extract facts) / transient (drop)

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"

Component	Description
AgentRouter	Rule-based routing with channel/peer/guild/team priority tiers
ThreadBindingManager	SQLite-backed persistent agent-to-thread bindings with TTL
RouteAndBind	One-step resolve: check cache → router → persist binding

🤖 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

Extra	What it adds
ui	TypeScript client (Web/Desktop/Mobile)
matrix	Matrix channel (matrix-nio)
whatsapp	WhatsApp channel (neonize)
voice	Voice TTS (edge-tts)
dev	Testing + linting (pytest, ruff, mypy)

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

Command	Description
maysii setup --wizard	Interactive setup wizard
maysii agent <message>	Run a single agent turn
maysii gateway	Start the gateway server
maysii node	Start a headless node host
maysii status [--deep]	Show status / probe health
maysii doctor	Run diagnostics

Configuration

Command	Description
maysii config list	Show all config
maysii config get <key>	Get a config value
maysii config set <key> <value>	Set a config value

Agents & Routing

Command	Description
maysii agents list	List agents
maysii agents add <name> --model <model>	Add an agent
maysii mode status	Show active collaboration mode
maysii mode switch <mode>	Switch orchestration mode
maysii skills list	List available skills
maysii exec-policy show|allow|deny	Manage tool execution policies

Channels & Messages

Command	Description
maysii channels list	List channels
maysii channels status	Connection status
maysii message send <channel> <text>	Send a message through a channel

Auth, MCP & Devices

Command	Description
maysii auth login --provider <name>	Add API key profile
maysii auth status	Show auth profiles
maysii mcp status	Show MCP servers and tools
maysii mcp list-tools	List available MCP tools
maysii devices list	List paired devices

Sessions & Models

Command	Description
maysii sessions list	List agent sessions
maysii models list	Show available models
maysii import chatgpt <path>	Import ChatGPT export

Security & System

Command	Description
maysii security audit	Run security audit
maysii service install	Install as system service
maysii logs [--follow]	Tail runtime logs
maysii health	Quick health check (Docker HEALTHCHECK)

Memory & Knowledge

Command	Description
maysii active-memory on|off	Toggle Active Memory
maysii wiki init	Initialize Wiki Vault
maysii token-aware init|scan|status	Token optimization tools

---

Supported Channels

Channel	Library	Type
Telegram	aiogram	Core
Discord	discord.py	Core
Slack	slack-bolt (Socket Mode)	Core
WhatsApp	neonize (Baileys)	Core
Signal	signal-cli JSON-RPC	Core
iMessage	imsg JSON-RPC	Core
X (Twitter)	X API v2	Core
Web	Built-in	Core
Feishu / Lark	Open Platform API	Extension
DingTalk	Stream Mode	Extension
QQ	QQ Bot	Extension
MS Teams	Bot Framework	Extension
Matrix	matrix-nio	Extension
IRC	Native TCP/TLS	Extension
LINE	Messaging API	Extension
Twitch	IRC/TLS	Extension
Nostr	NIP-04 relay	Extension
BlueBubbles	REST webhook	Extension
Google Chat	OAuth webhook	Extension
Mattermost	REST + WebSocket	Extension
Nextcloud Talk	REST webhook	Extension
Synology Chat	Incoming webhook	Extension
Tlon / Urbit	HTTP API	Extension
Zalo	Official API	Extension
Voice Call	Twilio	Extension

---

Supported LLM Providers

Core Providers

Provider	Models
OpenAI	GPT-4o, GPT-4o-mini, o1, o3-mini
Anthropic	Claude Opus 4.8, Claude Sonnet, Claude Haiku
Google Gemini	Gemini 2.0 Flash, Gemini Pro
Ollama	Any locally hosted model

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

Variable	Description
OPENAI_API_KEY	OpenAI API key
ANTHROPIC_API_KEY	Anthropic API key
GOOGLE_API_KEY	Google AI API key
TELEGRAM_BOT_TOKEN	Telegram bot token
MAYSII_GATEWAY_PORT	Gateway port (default: 18777)

---

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

Layer	Technology
Language	Python 3.10+
Type checking	mypy strict (0 errors)
Linting	ruff (clean)
Web framework	FastAPI + Uvicorn
WebSocket	websockets
CLI	Typer + Rich
Config format	JSON5 (Pydantic v2)
Database	SQLite + aiosqlite (WAL mode)
Vector search	LanceDB
UI (Web)	Next.js 15
UI (Desktop)	Tauri 2.x
UI (Mobile)	Expo React Native
Testing	pytest + pytest-asyncio
Build	Hatch

---

Project Stats

Metric	Value
Source files	755+ Python files
Tests	6,125 (6,125 passed, 1 skipped)
Code coverage	66%
Type safety	mypy strict: 0 errors
Channels	28
LLM providers	25+
Built-in tools	20+
CLI commands	30+
Gateway RPC methods	30+
MCP transports	3 (stdio, HTTP, Streamable HTTP)
MCP built-in servers	3 (Memory, RAG, Image Gen)
Context engine plugins	2 builtin + custom API
Multi-agent engines	5

---

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

Document	Description
Quick Start	Getting started guide
Architecture	System architecture (v5.0)
Configuration	Full config reference
Context Engine Plugin	Plugin development guide (v5.0)
API Reference	Gateway RPC + HTTP API
Channel Setup	Per-channel configuration
v5.1 ROADMAP	Next milestone plan

---

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