ApiliumCode · ApiliumDevTeam · Mar 12, 2026 · Mar 12, 2026 · Mar 12, 2026 · Mar 12, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,9 +4,54 @@ Product: https://apilium.com/us/products/mayros
 Download: https://mayros.apilium.com
 Docs: https://apilium.com/us/doc/mayros
 
+## 0.1.15 (2026-03-12)
+
+MCP Server production-ready, Claude Desktop and Claude Code integration, documentation, and product page update.
+
+### MCP Server
+
+- 9 tools exposed via Model Context Protocol: memory (remember, recall, search, forget), budget, governance, cortex (query, store, stats)
+- Cortex sidecar auto-starts on `mayros serve`, persistent storage at `~/.mayros/cortex-data/`
+- Dual transport: `--stdio` for IDE/Claude Desktop, `--http` for remote clients
+- Default port aligned to Mayros convention: 19100
+
+### MCP Setup
+
+- `mayros mcp-setup` — one-command registration for Claude Code (stdio or HTTP)
+- `mayros mcp-setup --desktop` — auto-configures Claude Desktop config file
+- Resolves absolute paths to `node` and `mayros.mjs` for Claude Desktop compatibility
+- Cross-platform config detection: macOS, Windows, Linux
+
+### Documentation
+
+- New: `tools/mcp-server.mdx` — architecture, 9 tools reference, setup guides, configuration
+- New: `cli/mcp-setup.mdx` — CLI reference with options and platform-specific paths
+- Updated: `cli/serve.mdx` — port 19100, tools table, Cortex sidecar section
+- Updated: `README.md` — step-by-step MCP setup guides, usage examples
+
+### Product Page
+
+- New capability cards: Intelligent Model Routing (Q-learning) and Policy Enforcement (governance)
+- Updated capabilities: HNSW vector search, Byzantine consensus, response caching, budget tracking
+- Updated architecture layers: Q-learning routing, governance gates, MCP Server, WASM transforms
+- Security layers expanded from 6 to 10 (governance gates, HMAC audit trail, trust tiers, rate limiting)
+- Updated numbers: 67 extensions, 75+ CLI commands, 20 security layers
+- FAQ updated with MCP server and HNSW references
+
+### Badges
+
+- MCP Compatible badge (shields.io)
+- Works with Claude badge (Anthropic logo)
+
+### Infrastructure
+
+- Require AIngle Cortex >= 0.4.3
+
+---
+
 ## 0.1.14 (2026-03-11)
 
-Intelligent routing, multi-agent consensus, and execution safety.
+Intelligent routing, multi-agent consensus, execution safety, code transforms, governance, dual-platform coordination, and MCP server enhancements.
 
 ### Eruberu — Adaptive Model Routing
 
@@ -54,10 +99,50 @@ Intelligent routing, multi-agent consensus, and execution safety.
 - `buildFromPricingCatalog()`: construct router from token-economy pricing catalog
 - `routeWithBudget()`: budget-aware routing that filters by remaining spend
 
+### Hayameru — WASM Code Transforms
+
+- Deterministic code transforms that bypass LLM for simple edits (0 tokens, sub-millisecond)
+- Intent detector: keyword-based prompt classification with confidence scoring
+- 5 transforms: var→const, remove console, sort imports, add semicolons, remove comments
+- Path safety validation and atomic file writes
+- Integrates via `before_agent_run` hook — short-circuits LLM when confidence is high
+- Metrics tracking: token savings, transform counts, timing
+
+### Kimeru — Byzantine & Raft Consensus
+
+- Byzantine fault tolerance: HMAC-SHA256 signed votes, PBFT phases (pre-prepare → prepare → commit)
+- Quorum math: 2f+1 agreement required, minimum 4 agents, auto-fallback to weighted
+- Raft leader election: highest EMA score wins, majority follower confirmation
+- Re-election support with agent exclusion
+
+### Osameru — Governance Control Plane
+
+- Policy compiler: parses MAYROS.md for ALLOW/DENY/REQUIRE-APPROVAL rules
+- Enforcement gate: evaluates tool calls, agent starts, and content against policy bundle
+- HMAC-signed append-only audit trail with hash chain integrity verification
+- Trust tiers: 3-level system (new → established → trusted) based on EMA performance scores
+- Configurable modes: enforce, warn, audit-only, off
+
+### Kakeru — Dual-Platform Bridge
+
+- Platform bridge interface for heterogeneous agent coordination
+- Claude bridge: native subagent integration (always connected)
+- Codex bridge: subprocess-based OpenAI Codex CLI integration with git branch isolation
+- Coordinator: parallel task execution, file lock coordination, branch management
+
+### MCP Server Enhancements
+
+- 9 dedicated MCP tools: remember, recall, search, forget, budget, policy_check, cortex_query, cortex_store, memory_stats
+- Auto-start Cortex sidecar when running `mayros serve`
+- Legacy SSE transport (MCP spec 2024-11-05) for Claude Desktop compatibility
+- `mayros mcp-setup` command for one-step registration in Claude Code
+- Enhanced health endpoint with Cortex sidecar status
+
 ### Infrastructure
 
 - 55 extensions synced at v0.1.14
-- 55 new tests across 7 test files (Q-Learning, task classification, routing, performance tracking, consensus, rate limiting, loop breaking)
+- 112 Phase 2 tests across 16 test files (transforms, intent detection, Byzantine consensus, Raft election, policy compilation, audit trail, trust tiers, enforcement, platform coordination)
+- 55 Phase 1 tests across 7 test files (Q-Learning, task classification, routing, performance tracking, consensus, rate limiting, loop breaking)
 - Auto-release workflow: GitHub Releases created automatically on version tags
 
 ## 0.1.13 (2026-03-08)

diff --git a/Dockerfile b/Dockerfile
@@ -1,4 +1,4 @@
-FROM node:25-bookworm@sha256:c4bfed36421c310d1fbb6dc51faf98065768fbc1c2c1ddd554813ecaa81bb2db
+FROM node:25-bookworm@sha256:2e45682ea560ac050cca0fd1ff5e82457a717a98e95e30bbf93306833a31332c
 
 # Install Bun (required for build scripts)
 RUN curl -fsSL https://bun.sh/install | bash

diff --git a/README.md b/README.md
@@ -23,6 +23,8 @@
   <img src="https://img.shields.io/badge/TypeScript-strict-3178C6?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript">
   <img src="https://img.shields.io/badge/extensions-55-8B5CF6?style=for-the-badge" alt="55 extensions">
   <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-999?style=for-the-badge" alt="macOS | Linux">
+  <img src="https://img.shields.io/badge/MCP-Compatible-6366F1?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyem0wIDE4Yy00LjQyIDAtOC0zLjU4LTgtOHMzLjU4LTggOC04IDggMy41OCA4IDgtMy41OCA4LTggOHoiLz48cGF0aCBkPSJNMTIgNmMtMy4zMSAwLTYgMi42OS02IDZzMi42OSA2IDYgNiA2LTIuNjkgNi02LTIuNjktNi02LTZ6Ii8+PC9zdmc+" alt="MCP Compatible">
+  <img src="https://img.shields.io/badge/Works_with-Claude-D97706?style=for-the-badge&logo=anthropic&logoColor=white" alt="Works with Claude">
 </p>
 
 <p align="center">
@@ -31,9 +33,9 @@
 
 ---
 
-**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. All backed by a local-first Gateway and an 18-layer security architecture.
+**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. All backed by a local-first Gateway and an 20-layer security architecture.
 
-> **55 extensions · 9,200+ tests · 29 hooks · MCP support · Multi-model · Multi-agent**
+> **55 extensions · 11,700+ tests · 29 hooks · MCP server & client · Multi-model · Multi-agent**
 
 ```bash
 npm install -g @apilium/mayros@latest
@@ -50,11 +52,11 @@ mayros code   # interactive coding CLI
 | 🧠 **Knowledge Graph** | AIngle Cortex — persistent memory across sessions, projects, and agents                              | Flat conversation history |
 | 🤖 **Multi-Agent**     | Teams, workflows, mailbox, background tasks, git worktree isolation                                  | Single agent              |
 | 📱 **Multi-Channel**   | 17 channels — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Teams, Matrix, WebChat, and more | Terminal only             |
-| 🔒 **Security**        | 18 layers — WASM sandbox, bash scanner, interactive permissions, namespace isolation, rate limiter   | Basic sandboxing          |
+| 🔒 **Security**        | 20 layers — WASM sandbox, bash scanner, interactive permissions, namespace isolation, rate limiter   | Basic sandboxing          |
 | 🎙️ **Voice**           | Always-on Voice Wake + Talk Mode on macOS, iOS, Android                                              | None                      |
 | 🖥️ **IDE**             | VSCode + JetBrains plugins with chat, plan, traces, KG                                               | VSCode only               |
 | 📊 **Observability**   | Full trace system, decision graph, session fork/rewind                                               | Basic logging             |
-| 🔌 **Extensions**      | 55 plugin extensions, 29 hook types, MCP client (4 transports)                                       | Limited plugins           |
+| 🔌 **Extensions**      | 55 plugin extensions, 29 hook types, MCP server + client (4 transports)                              | Limited plugins           |
 | 🗺️ **Plan Mode**       | Cortex-backed semantic planning: explore → assert → approve → execute                                | Simple plan files         |
 
 ---
@@ -157,8 +159,10 @@ Full beginner guide: **[Getting started](https://apilium.com/en/doc/mayros/start
                                    │
           ┌────────────┬───────────┼───────────┬────────────┐
           │            │           │           │            │
-     mayros code   VSCode /   Pi Agent    macOS App    iOS/Android
-      (TUI)       JetBrains   (RPC)      (menu bar)     Nodes
+     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.
@@ -205,16 +209,91 @@ 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](https://modelcontextprotocol.io). Any MCP client — Claude Desktop, Claude Code, VSCode, Cursor, JetBrains — can discover and use Mayros capabilities.
+
+### Connect with Claude Desktop
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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).
+
+### Tools
+
+| Tool                  | Description                                           |
+| --------------------- | ----------------------------------------------------- |
+| `mayros_remember`     | Store information in persistent semantic memory       |
+| `mayros_recall`       | Search memory by text, tags, or type                  |
+| `mayros_search`       | Vector similarity search over memory (HNSW)           |
+| `mayros_forget`       | Delete a memory entry                                 |
+| `mayros_budget`       | Check token usage and budget status                   |
+| `mayros_policy_check` | Evaluate actions against governance policies          |
+| `mayros_cortex_query` | Query the knowledge graph by subject/predicate/object |
+| `mayros_cortex_store` | Store RDF triples in the knowledge graph              |
+| `mayros_memory_stats` | STM/LTM/HNSW/graph statistics                         |
+
+---
+
+## 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`
 
@@ -256,15 +335,21 @@ Both connect to `ws://127.0.0.1:18789`.
 | Category      | Extension                 | Purpose                                                                   |
 | ------------- | ------------------------- | ------------------------------------------------------------------------- |
 | Skills        | `semantic-skills`         | QuickJS WASM sandbox, 6 semantic tools, skill marketplace                 |
-| Agents        | `agent-mesh`              | Teams, workflows, delegation, mailbox, background tasks                   |
+| Agents        | `agent-mesh`              | Teams, workflows, consensus (majority/weighted/Byzantine/Raft), mailbox   |
 | Memory        | `memory-semantic`         | Cortex integration, rules engine, agent memory, contextual awareness      |
 | Observability | `semantic-observability`  | Traces, decision graph, session fork/rewind                               |
 | Indexer       | `code-indexer`            | Codebase scanning + RDF mapping (incremental)                             |
 | Security      | `bash-sandbox`            | Command parsing, domain checker, blocklist, audit log                     |
+| Governance    | `osameru-governance`      | Policy enforcement, HMAC audit trail, trust tiers                         |
 | Permissions   | `interactive-permissions` | Runtime permission dialogs, intent classification, policy store           |
+| Routing       | `eruberu`                 | Q-Learning model routing, budget-driven fallback, task classification     |
+| Transforms    | `hayameru`                | Deterministic code transforms that bypass LLM (0 tokens, sub-ms)          |
+| Rate Limit    | `tomeru-guard`            | Sliding window rate limiter, loop breaker, velocity circuit breaker       |
 | Hooks         | `llm-hooks`               | Markdown-defined hook evaluation with safe condition parser               |
-| MCP           | `mcp-client`              | Model Context Protocol client (stdio, SSE, WebSocket, HTTP)               |
-| Economy       | `token-economy`           | Budget tracking, prompt cache optimization                                |
+| MCP Server    | `mcp-server`              | 9 tools exposed via MCP (memory, budget, governance, graph)               |
+| MCP Client    | `mcp-client`              | Model Context Protocol client (stdio, SSE, WebSocket, HTTP)               |
+| Economy       | `token-economy`           | Budget tracking, response cache, prompt cache optimization                |
+| Bridge        | `kakeru-bridge`           | Dual-platform coordination (Claude + Codex CLI)                           |
 | Hub           | `skill-hub`               | Apilium Hub marketplace, Ed25519 signing, dependency audit                |
 | IoT           | `iot-bridge`              | IoT node fleet management                                                 |
 | Channels      | 17 plugins                | Discord, Telegram, WhatsApp, Slack, Signal, iMessage, Teams, Matrix, etc. |
@@ -284,9 +369,9 @@ Both connect to `ws://127.0.0.1:18789`.
 
 ---
 
-## Security (18 layers)
+## Security (20 layers)
 
-Mayros takes security seriously. 18 layers of defense:
+Mayros takes security seriously. 20 layers of defense:
 
 | Layer                       | Description                                                     |
 | --------------------------- | --------------------------------------------------------------- |
@@ -307,6 +392,8 @@ Mayros takes security seriously. 18 layers of defense:
 | DM Pairing                  | Unknown senders get pairing code, not access                    |
 | Audit Logging               | Skill name + operation tagged on all sandbox writes             |
 | Docker Sandboxing           | Per-session Docker containers for non-main sessions             |
+| Governance (Osameru)        | Policy compilation, enforcement gates, HMAC audit trail         |
+| Rate Limit (Tomeru)         | Sliding window, token bucket, loop breaking, velocity breaker   |
 | Enterprise Managed Settings | Enforced config overrides with locked keys                      |
 
 ---