⚡🛡️ Mayros

AI agent framework · Coding CLI · Personal assistant
One platform. Your terminal, your channels, your devices.

Product · Download · Docs · Getting Started · Vision · Discord

Mayros is an open-source AI agent framework that runs on your own devices. It ships with an interactive coding CLI (mayros code), connects to 17+ messaging channels (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Teams, and more), speaks and listens on macOS/iOS/Android, and has a knowledge graph that remembers everything across sessions. Kaneru — the multi-agent venture system — lets you build AI companies that learn, remember, and improve over time. All backed by a local-first Gateway and a 20-layer security architecture.

55+ extensions · 12,400+ tests · 29 hooks · MCP server & client · Multi-model · Multi-agent · Kaneru ventures

npm install -g @apilium/mayros@latest
mayros onboard
mayros code   # interactive coding CLI

Why Mayros?

Install

Runtime: Node ≥ 22. Works with npm, pnpm, or bun.

npm install -g @apilium/mayros@latest
# or: pnpm add -g @apilium/mayros@latest

mayros onboard --install-daemon

The wizard sets up the Gateway, workspace, channels, and skills. It installs the Gateway as a background daemon (launchd/systemd) so it stays running.

The installer automatically downloads AIngle Cortex (the semantic memory sidecar). No separate install needed.

New install? Start here: Getting Started · Upgrading? Updating guide (and run mayros doctor)

Update

mayros update          # updates Mayros + Cortex automatically
# or: npm install -g @apilium/mayros@latest

Uninstall

mayros uninstall           # interactive — choose what to remove
mayros uninstall --all     # remove everything (service, state, workspace, cortex)
mayros uninstall --dry-run # preview without deleting

A detailed data loss warning is always shown before deletion — listing every category of data (knowledge graph, ventures, agent memory, decision history, etc.).

Desktop Installers

Zero-setup installers that bundle Node.js + AIngle Cortex — no prerequisites required.

Each installer includes Node.js portable + AIngle Cortex binary, runs npm install at install time, creates desktop shortcuts, and adds Mayros to the system PATH.

Local Models

Run models locally with automatic GPU detection and guided setup. Mayros detects your hardware and recommends compatible models.

Supported runtimes:

GPU detection: NVIDIA (nvidia-smi), AMD/Intel (PowerShell on Windows, lspci on Linux), Apple Silicon (sysctl), Intel Mac (system_profiler), Raspberry Pi (BCM2 chipset).

50+ model catalog segmented by 8 activities (coding, chat, reasoning, creative, analysis, multilingual, vision, agents) with VRAM-aware filtering — from CPU-only models (0 VRAM) to 80GB+ enterprise models.

mayros mamoru model detect     # detect GPU and recommend models
mayros mamoru model catalog    # browse full catalog by activity
mayros mamoru model install    # guided installation

The onboarding wizard in the web portal also includes GPU-aware model selection with compatibility indicators.

Coding CLI

mayros code is an interactive terminal UI for coding, conversation, and agent-driven workflows.

mayros code                    # interactive TUI session
mayros tui                     # alias
mayros -p "refactor auth flow" # headless mode (non-interactive)

Features:

• 🎨 3 themes (dark, light, high-contrast) — /theme
• 📝 3 output styles (standard, explanatory, learning) — /style
• ⌨️ Vim mode with motions, operators, undo — /vim
• 📋 Ctrl+V image paste from clipboard
• 📊 /diff inline diff viewer · /context token usage chart
• 🗺️ /plan semantic plan mode (Cortex-backed)
• 📎 /copy to clipboard · /export [file] to disk
• 🔀 /model switch models · /think set thinking level · /fast toggle fast mode

Slash commands (30+):

Markdown-driven extensibility:

• Custom agents: ~/.mayros/agents/*.md — define persona, tools, and behavior in markdown
• Custom commands: ~/.mayros/commands/*.md — define slash commands as markdown templates

Quick Start

# 1. Install and onboard
mayros onboard --install-daemon

# 2. Start the Gateway
mayros gateway --port 18789 --verbose

# 3. Code interactively
mayros code

# 4. Or use the agent directly
mayros agent --message "Ship checklist" --thinking high

# 5. Or send a message to any channel
mayros message send --to +1234567890 --message "Hello from Mayros"

Full beginner guide: Getting started

Architecture

  WhatsApp · Telegram · Slack · Discord · Signal · iMessage · Teams · Matrix · WebChat
                                    │
                                    ▼
                    ┌───────────────────────────────┐
                    │          ⚡ Gateway             │
                    │     (local control plane)      │
                    │     ws://127.0.0.1:18789       │
                    └──────────────┬────────────────┘
                                   │
          ┌────────────┬───────────┼───────────┬────────────┐
          │            │           │           │            │
     mayros code   VSCode /   Pi Agent    macOS App    MCP Server
      (TUI)       JetBrains   (RPC)      (menu bar)   :19100
                                                     Claude Desktop
                                                     Claude Code

The Gateway is the single control plane — every client, channel, tool, and event connects through it.

Multi-Channel Inbox

Mayros connects to the channels you already use. One assistant, everywhere.

Security defaults: DM pairing — unknown senders get a pairing code. You approve with mayros pairing approve <channel> <code>. Public DMs require explicit opt-in.

Knowledge Graph (AIngle Cortex)

Mayros remembers. Not just conversation history — semantic knowledge stored as RDF triples in AIngle Cortex.

Three-tier memory:

1. MAYROS.md — flat-file persona and instructions, always loaded into the system prompt
2. AIngle Cortex — RDF triple store (subject → predicate → object) scoped by namespace. Optional: falls back to file-based memory when unavailable
3. Ineru STM/LTM — short-term and long-term memory with temporal recall

Built on top:

• Code indexer — scans your codebase → RDF triples in Cortex (incremental, only re-indexes changed files)
• Project memory — persists conventions, findings, and architecture decisions across sessions
• Smart compaction — extracts key information before context pruning
• Cross-session recall — injects relevant knowledge from previous sessions into new prompts

Design principles: namespace isolation (no cross-namespace reads), graceful degradation (Cortex is a sidecar, not an FFI binding), circuit breaker with exponential backoff.

CLI: mayros kg search|explore|query|stats|triples|namespaces|export|import

MCP Server

Mayros exposes its tools, resources, and prompts via the Model Context Protocol. Any MCP client — Claude Desktop, Claude Code, VSCode, Cursor, JetBrains — can discover and use Mayros capabilities.

Connect with Claude Desktop

# 1. Install Mayros
npm install -g @apilium/mayros@latest

# 2. Register with Claude Desktop (auto-detects paths, writes config)
mayros mcp-setup --desktop

# 3. Restart Claude Desktop — done
#    The tools icon appears in the chat input

Then in Claude Desktop, just talk naturally:

• "Remember that our API uses JWT tokens with 24h expiry" → stores in semantic memory
• "What do you know about our authentication?" → recalls from memory and knowledge graph
• "Store in the graph: project:api depends_on express v5" → creates an RDF triple
• "What's the memory status?" → shows STM/LTM/graph statistics

Connect with Claude Code

# From your terminal (not inside a Claude Code session)
mayros mcp-setup
# or manually:
claude mcp add mayros -- mayros serve --stdio

Connect with other MCP clients

# Start the HTTP server
mayros serve --http
# → MCP endpoint: http://127.0.0.1:19100/mcp
# → Legacy SSE:   http://127.0.0.1:19100/sse
# → Health check: http://127.0.0.1:19100/health

Point any MCP client to http://127.0.0.1:19100/mcp (Streamable HTTP) or http://127.0.0.1:19100/sse (legacy SSE for older clients).

Bring persistent memory to any AI coding tool

AI coding CLIs have no memory between sessions. Mayros + AIngle Cortex fill that gap: semantic knowledge graph, DAG audit trail, vector search, and ZK proofs — all local-first.

Any MCP-compatible client gets instant access to 45+ tools via a single command:

claude mcp add mayros -- mayros serve --stdio   # Claude Code
# Gemini CLI, GitHub Copilot — coming soon

Built on the open Model Context Protocol standard — no vendor lock-in.

Tools

Intelligent Routing

Adaptive routing that learns and improves over time.

• Eruberu (Q-Learning model routing) — learns optimal provider/model per task type, budget level, and time slot
• Miteru (task-to-agent routing) — learns which agent handles each task type best via EMA scoring
• Hayameru (code transforms) — deterministic WASM transforms that bypass the LLM for simple edits (var→const, remove console, sort imports). 0 tokens, sub-millisecond

CLI: mayros routing status|strategy|reset

Multi-Agent Mesh

Agents that work together. Mayros supports coordinated multi-agent workflows with shared knowledge.

• Team manager — Cortex-backed lifecycle: create, assign roles, merge results, disband
• Workflow orchestrator — built-in workflows (code-review, research, refactor) + custom definitions
• Kimeru consensus — majority vote, weighted (EMA), LLM-arbitrated, Byzantine (PBFT with HMAC), Raft leader election
• Agent mailbox — persistent inter-agent messaging (send/inbox/outbox/archive)
• Background task tracker — long-running tasks with status and cancellation
• Git worktree isolation — each agent works in its own worktree to avoid conflicts
• Session fork/rewind — checkpoint-based exploration with rewind capability
• Kakeru bridge — dual-platform coordination (Claude + Codex CLI) with file lock coordination

CLI: mayros workflow run|list · mayros dashboard team|summary|agent · mayros tasks list|status|cancel|summary · mayros mailbox list|read|send|archive|stats

Kaneru — AI Venture Management

Kaneru turns Mayros into a full AI venture platform. Create organizations of agents that learn, coordinate, and improve over time — all stored in Cortex, all DAG-auditable.

Kaneru Quick Start

# Install a pre-built venture template (security-audit, content-pipeline, devops-squad)
mayros kaneru dojo install --template security-audit --name "My Security Team"

# Or use the web portal Setup Wizard: open dashboard → Ventures → New Venture
mayros dashboard

Ventures & Missions

mayros kaneru venture create --name "Acme" --prefix ACM --directive "Ship fast" --fuel-limit 10000
mayros kaneru mission create --venture <id> --title "Audit auth module" --priority critical
mayros kaneru mission claim --mission <id> --agent scanner --run run-001
mayros kaneru mission transition --mission <id> --status review --run run-001
mayros kaneru comment add --mission <id> --author scanner --content "SQL injection found"

Agents That Learn

Agents build expertise profiles over time. Q-learning + EMA scoring routes missions to the best agent automatically.

mayros kaneru learn profile --agent scanner     # see agent expertise
mayros kaneru learn top --domain typescript --task-type security-scan  # best agents for a task
mayros kaneru route --mission "Fix SQL injection" --agents scanner,reviewer,fixer  # smart routing

Cost Analytics & Fuel Control

mayros kaneru fuel summary --venture <id>           # spend overview
mayros kaneru fuel analytics --venture <id> --period weekly  # time-series + provider breakdown
mayros kaneru fuel forecast --venture <id>           # burn rate + days until exhausted

Decision Audit

mayros kaneru consensus --squad <id> --question "Ship or block?"
mayros kaneru decisions list --venture <id>
mayros kaneru decisions explain --decision <id>     # full reasoning with votes

Distributed Ventures (P2P)

mayros kaneru discover --venture <id>    # auto-discover peers via mDNS
mayros kaneru sync --venture <id>        # DAG-sync venture state with peers

Web Portal

The portal at http://localhost:18789 includes:

• Ventures tab — venture table, mission kanban, chain of command tree, fuel bars
• Kaneru tab — squads, Q-learning router, squad builder
• Canvas tab — A2UI surfaces (overview, missions, chain, fuel) — interactive, venture-aware
• Setup Wizard — 4-step guided venture creation (Venture → Agent → Mission → Launch)
• Command Bar (Ctrl+/) — Spotlight-style overlay with venture context and voice input

MCP Tools (24)

Any MCP client (Claude, Cursor, Cline) gets access to 24 Kaneru tools:

CLI: mayros kaneru — 18 subcommand groups with 40+ commands total

Mamoru — Security Layer

Mamoru (守る, "to protect") adds enterprise-grade security to Mayros:

• Sandbox — Landlock + seccomp probing for kernel-level agent isolation (Linux)
• Eruberu Proxy — All inference calls routed through the gateway with audit logging
• Mamoru Gate — Deny-by-default network egress with 12 presets and real-time approval
• Secrets Vault — AES-256-GCM encrypted secrets with scrypt key derivation
• API Keys — SHA-256 hashed agent keys with timing-safe validation
• Local Models — GPU detection + guided Ollama/vLLM setup

CLI: mayros mamoru status|egress|proxy|keys|vault|model

IDE Plugins

Mayros lives inside your editor, connected via Gateway WebSocket.

VSCode (tools/vscode-extension/):

• Sidebar tree views: sessions, agents, skills
• Webview panels: chat, plan mode, trace viewer, knowledge graph
• Context menu actions and gutter markers

JetBrains (tools/jetbrains-plugin/):

• Unified tabbed panel with the same feature set
• Protocol v3 compatibility

Both connect to ws://127.0.0.1:18789.

Voice & Companion Apps

• Voice Wake + Talk Mode — always-on speech for macOS/iOS/Android with ElevenLabs
• Live Canvas — agent-driven visual workspace with A2UI
• macOS app — menu bar control, Voice Wake, Talk Mode overlay, WebChat, debug tools
• iOS node — Canvas, Voice Wake, Talk Mode, camera, screen recording, Bonjour pairing
• Android node — Canvas, Talk Mode, camera, screen recording, optional SMS

Extensions Ecosystem

55 extensions loaded as plugins at startup:

Hooks System

29 hook types across the assistant lifecycle:

• Lifecycle — before_prompt_build, after_response, before_compaction, agent_end, etc.
• Security — permission_request (modifying: allow/deny/ask), config_change
• Coordination — teammate_idle, task_completed, notification
• HTTP webhooks — POST delivery with HMAC-SHA256 signatures, retry + exponential backoff
• Async queue — background execution with concurrency limits and dead-letter queue
• Markdown hooks — place .md files in ~/.mayros/hooks/ for custom logic

Security (20 layers)

Mayros takes security seriously. 20 layers of defense:

Models

Mayros is multi-model. Bring any provider.

• Models config + CLI: Models
• Auth profile rotation (OAuth vs API keys) + fallbacks: Model failover

Minimal config:

{
  agent: {
    model: "anthropic/claude-opus-4-6",
  },
}

Full reference: Configuration

Plan Mode

Cortex-backed semantic planning for complex multi-step tasks.

• Explore — gather context from the codebase and Cortex graph
• Assert — declare facts and constraints the plan must satisfy
• Approve — review the plan before execution
• Execute — run the approved plan with progress tracking

CLI: mayros plan start|explore|assert|show|approve|execute|done|list|status · TUI: /plan

Remote Gateway

Run the Gateway on a small Linux instance. Clients connect over Tailscale Serve/Funnel or SSH tunnels, and device nodes (macOS/iOS/Android) handle local actions via node.invoke.

Tailscale modes: off (default) · serve (tailnet-only HTTPS) · funnel (public HTTPS, requires password auth).

Details: Remote access · Tailscale guide · Docker

Chat Commands (Channels)

Send these in WhatsApp/Telegram/Slack/Discord/Google Chat/Microsoft Teams/WebChat:

From Source

git clone https://github.com/ApiliumCode/mayros.git
cd mayros

pnpm install
pnpm ui:build   # auto-installs UI deps on first run
pnpm build

pnpm mayros onboard --install-daemon

# Dev loop (auto-reload)
pnpm gateway:watch

pnpm mayros ... runs TypeScript directly (via tsx). pnpm build produces dist/.

Development channels:

• stable — tagged releases, npm dist-tag latest
• beta — prerelease tags, npm dist-tag beta
• dev — moving head of main, npm dist-tag dev

Switch: mayros update --channel stable|beta|dev. Details: Development channels

Skills Hub

Skills Hub is a skill marketplace. With it enabled, the agent can search for skills automatically and pull in new ones.

• Workspace root: ~/.mayros/workspace
• Skills: ~/.mayros/workspace/skills/<skill>/SKILL.md
• Injected prompt files: AGENTS.md, SOUL.md, TOOLS.md

Channel Setup

{ channels: { telegram: { botToken: "123456:ABCDEF" } } }

{ channels: { discord: { token: "1234abcd" } } }

Documentation

Start here:

• Getting started — first-time setup
• Architecture — gateway + protocol model
• Configuration — every key + examples
• Security — security model and guidance

Platform guides:

macOS · iOS · Android · Linux · Windows (WSL2)

Operations:

Gateway runbook · Docker · Health checks · Doctor · Logging · Troubleshooting

Deep dives:

Agent loop · Sessions · Models · Presence · Streaming · Skills · Browser · Canvas · Nodes · Cron · Webhooks · Gmail Pub/Sub

Advanced:

Discovery + transports · Bonjour/mDNS · Gateway pairing · Tailscale · Remote gateway · Control UI · RPC adapters · TypeBox schemas

Templates:

AGENTS · BOOTSTRAP · IDENTITY · TOOLS · USER · Default AGENTS · Skills config

Community

See CONTRIBUTING.md for guidelines, maintainers, and how to submit PRs. AI/vibe-coded PRs welcome! 🤖

Special thanks to Mario Zechner for his support and for pi-mono.