<div align="center">

<svg xmlns="http://www.w3.org/2000/svg" viewBox="300 120 780 560" width="200" height="143">
    <path fill="#001E32" d="M585.89,613.5l1.11,47c0.06,2.49-1.91,4.55-4.39,4.61c-2.49,0.06-4.55-1.91-4.61-4.39c0-0.07,0-0.15,0-0.21l1.11-47c0.04-1.87,1.6-3.35,3.47-3.31C584.4,610.23,585.84,611.7,585.89,613.5z"></path>
    <path fill="#001E32" d="M601.7,658.02l-21.48-18.15c-1.55-1.31-1.74-3.62-0.43-5.17c1.26-1.49,3.46-1.72,5-0.57l22.52,16.85c1.99,1.49,2.4,4.31,0.91,6.3c-1.49,1.99-4.31,2.4-6.3,0.91C601.84,658.14,601.76,658.08,601.7,658.02z"></path>
    <path fill="#001E32" d="M557.7,650.98l22.52-16.85c1.62-1.21,3.92-0.88,5.13,0.74c1.17,1.56,0.9,3.75-0.57,5l-21.48,18.15c-1.9,1.6-4.74,1.37-6.34-0.53c-1.6-1.9-1.37-4.74,0.53-6.34C557.55,651.09,557.63,651.03,557.7,650.98z"></path>
    <path fill="#001E32" d="M786.89,613.5l1.11,47c0.06,2.49-1.91,4.55-4.39,4.61c-2.49,0.06-4.55-1.91-4.61-4.39c0-0.07,0-0.15,0-0.21l1.11-47c0.04-1.87,1.6-3.35,3.47-3.31C785.4,610.23,786.84,611.7,786.89,613.5z"></path>
    <path fill="#001E32" d="M758.7,650.98l22.52-16.85c1.62-1.21,3.92-0.88,5.13,0.74c1.17,1.56,0.9,3.75-0.57,5l-21.48,18.15c-1.9,1.6-4.74,1.37-6.34-0.53c-1.6-1.9-1.37-4.74,0.53-6.34C758.55,651.09,758.63,651.03,758.7,650.98z"></path>
    <path fill="#001E32" d="M802.7,658.02l-21.48-18.15c-1.55-1.31-1.74-3.62-0.43-5.17c1.26-1.49,3.46-1.72,5-0.57l22.52,16.85c1.99,1.49,2.4,4.31,0.91,6.3c-1.49,1.99-4.31,2.4-6.3,0.91C802.84,658.14,802.76,658.08,802.7,658.02z"></path>
    <path fill="#58A6FF" d="M377.64,341.15l-54.89-12.2c-4.73-1.05-9.41,2.04-10.25,6.82c-3.05,17.39-2.64,54.92,58.14,53.38"></path>
    <path fill="#58A6FF" d="M988.36,341.15l54.89-12.2c4.73-1.05,9.41,2.04,10.25,6.82c3.05,17.39,2.64,54.92-58.14,53.38"></path>
    <path fill="#58A6FF" d="M979.65,273.5c-50.41-112.17-137.28-107.11-137.28-107.11L687,165l-155.37,1.39c0,0-86.87-5.06-137.28,107.11c0,0-144.86,286.86,166.46,344.07c0,0,53.32,11.6,126.19,11.75c72.87-0.15,126.19-11.75,126.19-11.75C1124.51,560.36,979.65,273.5,979.65,273.5z"></path>
    <path fill="#001E32" d="M927.07,253.4l-0.01-0.01C919.63,244.43,851,157,817,138c-13-8-25.7-9.74-34.43-10.35c-8.72-0.71-17.51,0.05-25.76,1.84c-12.8,2.06-57.54,29.38-58.46,29.97c-10.56,6.28-21.12,6.29-31.68,0c-18.36-11.86-44.98-27.8-58.47-29.98c-8.25-1.8-17.04-2.56-25.76-1.84C573.7,128.26,561,130,548,138c-34,19-102.63,106.43-110.06,115.39l-0.01,0.01c-7.14,8.61-7.18,21.37,0.42,30.05c8.43,9.63,23.08,10.6,32.7,2.16c5.88-5.85,86.94-86.61,107.68-95.22c2.92-1.02,5.79-1.58,8.66-1.89c2.88-0.22,5.82-0.26,8.98,0.24c1.75,0.07,31.51,13.43,55.68,24.35c19.67,8.88,42.21,8.82,61.84-0.15c23.82-10.89,53.05-24.13,54.72-24.2c3.16-0.5,6.1-0.46,8.98-0.24c2.87,0.31,5.73,0.87,8.66,1.89C807,199,888.07,279.76,893.94,285.61c9.63,8.43,24.27,7.47,32.7-2.16C934.25,274.77,934.21,262.01,927.07,253.4z"></path>
    <circle fill="#FFFAF5" cx="582.54" cy="364.71" r="111"></circle>
    <circle fill="#001E32" cx="582.54" cy="364.71" r="39"></circle>
    <circle fill="#FFFAF5" cx="783.46" cy="364.76" r="111"></circle>
    <circle fill="#001E32" cx="783.46" cy="364.76" r="39"></circle>
    <path fill="#187FC4" d="M718.59,415.27c-5.93-14.61-14.14-22.36-35.55-23.26c-0.03,0-0.06,0-0.08,0c-21.41,0.9-29.62,8.65-35.55,23.26c-2.85,7.04,2.27,14.73,9.87,14.73l25.72,0l25.72,0C716.32,430,721.44,422.3,718.59,415.27z"></path>
    <path fill="#187FC4" d="M718.59,443.73c-5.93,14.61-14.14,22.36-35.55,23.26c-0.03,0-0.06,0-0.08,0c-21.41-0.9-29.62-8.65-35.55-23.26c-2.85-7.04,2.27-14.73,9.87-14.73l25.72,0l25.72,0C716.32,429,721.44,436.7,718.59,443.73z"></path>
</svg>

# MUR

**The local-first AI agent platform, in native Rust.**

Run a fleet of specialized AI agents on the machine you already own — agents that
learn from every session, speak with an on-device voice, plug into the AI tools
you already use, and can be handed to a friend as a single file.

[![CI](https://github.com/mur-run/mur/actions/workflows/ci.yml/badge.svg)](https://github.com/mur-run/mur/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/mur-run/mur)](https://github.com/mur-run/mur/releases/latest)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
![Rust](https://img.shields.io/badge/Rust-2024_edition-orange?logo=rust)
![Platform](https://img.shields.io/badge/CLI-macOS_·_Linux_·_Windows-555)

[Quick start](#-quick-start) · [Features](#-what-can-a-mur-agent-do) · [Architecture](#-architecture) · [CLI](#-cli-at-a-glance) · [Docs](https://app.mur.run/docs/core) · [Website](https://mur.run)

</div>

---

<p align="center">
  <img src="assets/mur-hub.png" alt="MUR Hub — fleet dashboard with conversation rail, companion status, and desktop-pet style presets" width="92%" />
  <br/>
  <sub><b>MUR Hub</b> — your fleet's home: conversation rail, live agent status, desktop-pet style presets. UI in English · 繁體中文 · 简体中文.</sub>
</p>

## What is MUR?

Every AI tool you use today is stateless and cloud-tethered: each session starts
from zero, and the agent lives in someone else's datacenter. MUR inverts both
assumptions.

MUR runs **specialized agents as long-lived local processes** — each with its own
model binding, system prompt, MCP servers, skills, schedule, voice, and
permissions — supervised by one small Rust runtime speaking
[A2A v0.3](https://github.com/a2aproject/A2A). On top of the runtime sits a
**memory pipeline with a maturity lifecycle**: what an agent learns in one
session is captured, scored, stored as plain YAML, retrieved by hybrid semantic
search, and injected into the next session — and it decays when it stops being
useful, so no junk accumulates.

You talk to your fleet through the **MUR Hub** desktop app (chat, approvals,
desktop pets), by **voice**, from an **iPhone**, from the **terminal**, or
through **Slack / Telegram / Jira**. And when an agent becomes genuinely useful,
you can **export it as a signed `.muragent` file** and give it to someone who has
never heard of MUR.

> **In one line:** a native-Rust, local-first fleet of specialized AI agents that
> learn and evolve — light enough to be always-on on the Mac you already own, and
> each exportable as a companion you can hand to anyone.

### Why local-first?

- **It fits on your machine.** ~200K lines of native Rust — no Electron, no
  Python sidecar. An always-on fleet plus a local LLM fits in consumer RAM.
- **Marginal cost ≈ 0.** Inference runs on your hardware. Everything local is
  free, with no per-token meter.
- **Privacy is structural, not a setting.** Memory, recordings, telemetry, and
  voice stay under `~/.mur/`. Logs pass through a redaction chokepoint before
  they touch disk, and a compile-time test forbids the companion module from
  importing network clients.

### How MUR compares

| Capability | MUR | Agent harnesses<br>(Archon, …) | Coding agents<br>(Claude Code, Cursor) | Memory layers<br>(Mem0, Zep, …) |
|---|:-:|:-:|:-:|:-:|
| Local-first multi-agent runtime (native Rust) | ✅ | ✗ | ✗ | ✗ |
| Memory that evolves (decay + Draft→Canonical lifecycle) | ✅ | ✗ | ✗ | partial |
| Kernel sandbox (Landlock / seccomp / SBPL / Job Object) | ✅ | ✗ | ✗ | ✗ |
| Export an agent as a giveable artifact | ✅ | ✗ | ✗ | ✗ |
| On-device voice, DND-aware | ✅ | ✗ | ✗ | ✗ |
| Feeds learning into 16+ existing AI tools | ✅ | ✗ | partial | ✗ |

---

## 🚀 Quick start

### The 5-minute path — MUR Hub (macOS, Apple Silicon)

1. Download **[MUR-Hub-aarch64-apple-darwin.dmg](https://github.com/mur-run/mur/releases/latest)** from the latest release.
2. Drag **MUR Hub** into Applications and open it.
3. Say hi — the built-in concierge agent **MUR** is alive immediately: **offline,
   no API key, no signup**, running on a bundled local multimodal model.

Received a `.muragent` file from a friend? **Double-click it.** Hub verifies the
signature, walks you through model setup, and the agent comes alive.

> Power users: Hub menu → *Install Command-Line Tools…* puts `mur` on your `PATH`.

### The CLI path

```bash
# macOS / Linux
curl -fsSL https://mur.run/install.sh | sh

# Windows (PowerShell)
irm https://mur.run/install.ps1 | iex

# Homebrew (macOS arm64)
brew install mur-run/tap/mur

# From source
cargo install mur-core        # installs the `mur` binary
```

```bash
mur init                                      # interactive setup wizard
mur agent create coach --model llama3.2:3b    # create an agent (default provider: ollama)
mur agent install-service coach               # run it as a launchd/systemd user service
mur agent cli coach                           # streaming TUI chat with tool approvals
mur agent cli dev qa ops                      # three agents, tiled panes (tmux/zellij/WezTerm/kitty)
                                              #   --resume continues the last conversation
murmur coach                                  # quick form (murmur symlink), identical to mur agent cli coach
```

<p align="center"><img src="assets/demo.gif" alt="mur agent cli — streaming TUI chat with a local agent" width="92%" /></p>

In the chat, type `/` to open a completion menu of slash commands (with their subcommands) and the agent's skills — `↑↓` to move, `Tab`/`Enter` to accept, `Esc` to dismiss. And when the agent offers you choices, they appear as `Tab`-to-fill suggestions right in the input: a single one as greyed ghost text, several as a picker.

### Models & providers

Agents draw from a local provider/model registry at `~/.mur/models.yaml`:

```bash
mur model add gpt5 --provider openai --model gpt-5.2 --secret env:OPENAI_API_KEY
                                              # input/output pricing + context window are auto-filled
                                              #   from the models.dev catalog (--no-fetch to skip, or
                                              #   --input-cost/--output-cost to set them by hand)
mur model list                                # list registered models
mur model show gpt5                           # provider, model, effective in/out cost, context window
mur model prices refresh                      # refresh the cached models.dev price catalog
```

API keys are stored as `SecretRef`s (`env:`, `keychain:`, `file:`, `cmd:`) — never written to config in plaintext. The **MUR Hub** desktop app has a **Model Library** that connects cloud providers (key saved to the macOS Keychain), auto-detects local runtimes (Ollama / MLX / LM Studio), discovers their models via `/v1/models`, and adds them to the registry — no YAML editing required.

### Teach the AI tools you already use

MUR's memory layer works even if you never create an agent — it rides along with
Claude Code, Codex, Cursor, Gemini-family CLIs, and a dozen more:

```bash
mur init --hooks                              # install hooks for detected AI tools
mur sync                                      # write learned patterns into each tool's native config
mur notes search "how we handle auth errors"  # query your accumulated memory
```

---

## ✨ What can a MUR agent do?

### 🤖 Run as a real local process

One BusyBox-style runtime binary, one symlink per agent (`mur_agent_coach`).
Each agent owns its model binding (Ollama, MLX, Anthropic, OpenAI, … via the
`~/.mur/models.yaml` registry), system prompt, MCP servers, skills,
keychain-backed secrets, cron schedules, webhook receiver, and a rotating Ed25519
identity. `mur agent` exposes 40+ subcommands for the full lifecycle — create,
chat, export, schedule, permissions, telemetry, trash, rollback.

### 🧠 Learn — and forget — like a teammate

```mermaid
flowchart LR
    C["capture<br/>significance · feedback"] --> S["store<br/>YAML truth + vector index"]
    S --> R["retrieve<br/>vector 0.7 + BM25 0.3"]
    R --> I["inject<br/>hooks · MCP · prompts"]
    I -.->|next session| C
    E["evolve<br/>decay · maturity · recombination"] <-.-> S
```

Knowledge moves through a maturity lifecycle driven by real usage, with decay
half-lives by tier (session 14d / project 90d / core 365d):

```mermaid
stateDiagram-v2
    direction LR
    [*] --> Draft
    Draft --> Emerging: validated by usage
    Emerging --> Stable: repeated wins
    Stable --> Canonical: proven over months
    Canonical --> Stable: unused — decay
    Stable --> Emerging: unused — decay
```

Recurring tool sequences across sessions are mined into **suggested workflows**
(`mur workflow suggest`) — no drag-and-drop DAG editor, no marketplace; your own
recorded behavior is the authoring tool.

Capture is **ambient**: once hooks are installed, every session is recorded
locally (scrubbed at write, retention-GC'd, one line of config to turn off).
`mur in` just marks the current session as important; `mur out` reviews the
workflow proposals MUR harvested from your recent sessions — accept one and
it becomes a draft workflow you can run with `mur run`.

### 💬 Be everywhere you are

- **MUR Hub** — multi-conversation rail across the fleet, streaming replies,
  human-in-the-loop tool approvals, dashboards, and drag-out **desktop pets**
  with expressions and speech bubbles.
- **Voice** — fully on-device TTS (Kokoro 82M) + STT (whisper.cpp); respects
  Do Not Disturb, Focus, and a busy microphone.
- **iPhone** — the in-repo iOS companion (`mur-mobile-app`) pairs over LAN with
  `mur agent pair` (QR); off-LAN traffic falls back to a relay that forwards only
  end-to-end-signed envelopes. All AI stays on your Mac.
- **Watch together** — agents open videos in VLC, explain the current scene,
  analyze whole videos with timestamps, and (opt-in) comment on scene changes —
  on a local multimodal model.
- **Bridges** — Slack, Telegram, Jira (`@mur implement PROJ-123`), and webhooks.

### 🎁 Be given away

```mermaid
flowchart LR
    A["Your agent<br/>in Hub or CLI"] -- "Share /<br/>mur agent export" --> B["coach.muragent<br/>signed · sanitized · data-only"]
    B -- "any channel" --> C["Friend<br/>double-clicks"]
    C --> D["Hub verifies signature,<br/>guides model setup"]
    D --> E["Agent alive<br/>on their machine"]
```

The `.muragent` package is DSSE-signed and **contains no executable code and no
secrets** — private keys and API keys are stripped at export. The recipient
installs MUR Hub once (signed + notarized); after that, agents travel as plain
files.

### 🔐 Stay governed

- **Kernel sandbox** per OS — Landlock + seccomp (Linux), SBPL (macOS), Job
  Object (Windows) — plus a DNS-resolver guard that filters network egress.
- **Human-in-the-loop** — tool calls pause for your approval in Hub and in
  `mur agent cli` (opt out per session with `--auto`).
- **Deletion safety** — destructive file actions go through a trash with a
  cancel window and explicit restore (`mur agent trash`); nothing is
  hard-deleted on a timer.
- **Auditability** — every action lands in an append-only JSONL ledger;
  **MUR Commander** (companion crate) adds an Ed25519-signed constitution and a
  hash-chained audit log for cross-network fleets.

### 🔌 Power the tools you already pay for

Three integration layers, by interaction shape:

| Layer | Shape | What it does |
|---|---|---|
| **Hooks** | fire-and-forget | `mur sync` writes memory into each tool's native config; session hooks inject context automatically |
| **MCP server** | interactive | `mur-mcp-server` (stdio) exposes 18 tools — search, recall, project code search, agent status, token compression, media control |
| **Skills** | teaching | curated manifests that tell agents *when and why* to reach for MUR |

Synced tools include Claude Code, Gemini CLI, Auggie, Cursor, Copilot CLI,
OpenClaw, OpenCode, Amp, Codex, Aider, Windsurf, Zed, Junie, Trae, Cline, and
Amazon Q. The compression tools (`mur_compress` / `mur_retrieve`) shrink large
payloads 40–80%, reversibly — originals stay retrievable by hash.

---

## 🦀 Architecture

<p align="center">
  <img src="docs/diagrams/mur-architecture.svg" alt="MUR system architecture" width="100%" />
</p>

| Crate | Role |
|---|---|
| [`mur-core`](mur-core) | The `mur` CLI — memory pipeline, sync, sources, dashboard server, agent management |
| [`mur-common`](mur-common) | Shared types — `Pattern`, `Workflow`, A2A envelopes, `.muragent` format |
| [`mur-agent-runtime`](mur-agent-runtime) | Per-agent A2A v0.3 supervisor — sandbox, voice, export, telemetry |
| [`mur-daemon`](mur-daemon) | Always-on background daemon — queues, schedules, dashboard API |
| [`mur-mcp-server`](mur-mcp-server) | stdio MCP server exposing MUR to AI clients mid-conversation |
| [`mur-compress`](mur-compress) | Offline, reversible token compression |
| [`mur-gui-core`](mur-gui-core) | Shared GUI library — sidecar supervisor, companion bridge, A2A client |
| [`mur-agent-launcher`](mur-agent-launcher) | <100 KB per-agent stub (Dock identity, file association) |
| [`mur-mobile-sdk`](mur-mobile-sdk) | Rust mobile core (UniFFI → Swift/Kotlin) — transport, signed envelopes, audio framing |
| [`mur-hub-gui`](mur-hub-gui) | **MUR Hub** desktop app (Tauri 2 + React) |
| [`mur-mobile-app`](mur-mobile-app) | iOS voice companion (Swift) |

**MUR Commander** — the cross-network orchestration, governance, and
evaluation plane — ships as a separate crate.

On disk, everything lives under `~/.mur/`: agents, skills, notes, and workflows
as **human-readable, git-friendly YAML** (the source of truth), plus a
LanceDB vector index that is always rebuildable (`mur internals reindex`). No
opaque database lock-in.

---

## 🧰 CLI at a glance

```bash
mur daemon serve     # web dashboard at http://localhost:3847
mur dashboard        # terminal TUI dashboard
```

<details>
<summary><b>Full command tree</b> (24 top-level commands)</summary>

```
mur
├── init / doctor / update / stats / verify
├── agent        create · cli · send · card · export · install · companion · voice ·
│                pair · schedule · perm · secret · trash · queue · rollback … (40+)
├── fleet        create · list · show · run   (squads of agents over a shared channel)
├── skill        install · search · show · generate · suggest · evolve · recombine ·
│                publish · audit · trust · exchange · drafts · eval …
├── notes        create · search · list · show
├── workflow     run · suggest · list · schedule · show · search · new · publish · install
├── session      start · stop · record · status · list · review · show · export · push
├── sync         (16+ AI tools) · status · fleet pull/push/both
├── hook         unified hook entry for AI tools (prompt / tool / stop / session-start)
├── chat         conversations archive + ask
├── model        add · list · show · remove · migrate
├── source       external knowledge — Obsidian · Notion · Joplin
├── project      index · search   (semantic code search)
├── daemon       start · stop · status · serve · sleep
├── auth         login · logout
├── team         shared skills (private registries)
├── push / fetch signal outbox / inbox ↔ server
├── deploy       Docker Compose deployment
└── internals    low-level store access · reindex
```

</details>

---

## 🔨 Build from source

```bash
git clone https://github.com/mur-run/mur.git && cd mur

cargo build --workspace          # debug build (GUI apps are workspace-excluded)
cargo nextest run --workspace    # tests (CI uses nextest)
cargo clippy --workspace -- -D warnings

./build.sh                       # release build with the embedded web dashboard
./install.sh                     # build + install to /opt/homebrew/bin/mur
```

The two Tauri apps (`mur-hub-gui`, legacy `mur-agent-gui`) build from their own
manifests so the workspace build never pulls WebKitGTK / Cocoa / WebView2. The
iOS app builds with `mur-mobile-app/build-ios.sh`.

---

## 🧭 Roadmap

- **Cost-Router orchestrator** — route the easy ~80% of sub-tasks to local
  models and spawn a frontier coding agent (`claude` / `codex` / `agy`) only for
  the hard parts, as governed, sandboxed subprocesses. Spec merged; router in
  progress.
- **Fleet Sync (Pro)** — replicate your *evolved* fleet (profiles, skills,
  workflows, and their maturity/lifecycle state) across devices. Everything
  local stays free.
- **Hub on Windows / Linux**, and an **Android companion** from the same Rust
  mobile core.

Want to teach an agent something new? See
[Authoring Skills](docs/authoring-skills.md).

Design history lives in [`docs/superpowers/specs/`](docs/superpowers/specs) and
[`docs/architecture/runtime-overview.md`](docs/architecture/runtime-overview.md).

---

## 🤝 Contributing

Issues and PRs are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).

```bash
cargo nextest run --workspace && cargo clippy --workspace -- -D warnings
```

## 📄 License

[MIT](LICENSE)

---

<div align="center">
<sub><b>Local first. Native Rust. Yours.</b></sub><br/>
<sub><a href="https://mur.run">mur.run</a> · <a href="https://app.mur.run/docs/core">Docs</a> · <a href="https://github.com/mur-run/mur/releases">Releases</a> · <a href="https://github.com/mur-run/mur/issues">Issues</a></sub>
</div>
