Requirements: Git + Node.js >= 22.12 (24 LTS recommended) + pnpm 10

<p align="center">
  <img src="docs/assets/mascot.svg" alt="Muse — the bluebird mascot" width="120" />
</p>

<p align="center"><i>Meet Muse — a personal AI project built to understand the life you are already living.</i></p>

<h1 align="center">Muse</h1>

<p align="center">
  <b>Building a personal AI that learns how you live and work—and gets better at knowing when and how to help.</b><br/>
  <i>Local-first, provider-neutral, and honest about what is not built yet.</i>
</p>

<p align="center">
  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-green.svg" /></a>
  <a href="package.json"><img alt="Node ≥ 22.12" src="https://img.shields.io/badge/node-%E2%89%A5%2022.12-43853d.svg" /></a>
  <a href="https://www.typescriptlang.org/"><img alt="TypeScript" src="https://img.shields.io/badge/built%20with-TypeScript-3178c6.svg" /></a>
  <a href="#what-muse-will-not-do-boundaries"><img alt="Local-first" src="https://img.shields.io/badge/privacy-local--first-6f42c1.svg" /></a>
  <a href="https://ollama.com"><img alt="Runs on Ollama" src="https://img.shields.io/badge/runs%20on-Ollama-000000.svg" /></a>
  &nbsp;·&nbsp; <a href="README.ko.md">한국어</a>
</p>

Muse is meant to be a continuing personal agent for one person's life and work—not only a
work assistant. It should remember context, coordinate personal tools, stay quiet when that
is better, and learn whether its last suggestion actually helped. We call this
**Attunement**: learning how to live and work well with you, not only storing facts about you.

The first proof point is **Personal Continuity**: helping you pick up an unfinished thread
without reconstructing it from scratch. That thread might be a project, a trip, a health
appointment, someone you meant to contact, or an article you were reading. In the first
version, you choose the thread and its related Muse items; automatic detection comes later.
The first local CLI slice now works with explicit local tasks and notes: create a thread,
link exact sources, run `muse continue`, then record whether it helped. Automatic detection,
timing, and observation remain later work. **Work Resumption** is one specialized use of it,
not Muse's whole identity.

> **What works today:** personal memory, grounded recall, local personal stores, opt-in
> ambient snapshots, pattern and interruption controls, guarded browser actions, traces,
> checkpoints, and the first local Personal Continuity path. **What comes next:** more source
> adapters, opt-in observation, and better timing. See the
> [product contract](docs/strategy/attunement.md) and [implementation plan](docs/goals/attunement-implementation-plan.md).

<p align="center"><img src="docs/images/web-home.png" alt="Muse console home — model chip, integrations, what Muse has learned" width="860" /></p>

---

## 📊 Muse in numbers

Every number is reproducible from this repo — the command that generates it is in the last column.

| Metric | Value | How to reproduce |
| --- | --- | --- |
| Grounding-gate delta, self-authored corpus | **+0.94 faithfulness** at **0.00 false-refusal** (gate ON vs OFF, same gemma4:12b) | `pnpm eval:grounding-delta` → [`docs/benchmarks/RESULTS.md`](docs/benchmarks/RESULTS.md) |
| Grounding-gate delta, SQuAD-2.0 slice | **+0.63 faithfulness** at **0.00 false-refusal** | `pnpm eval:grounding-delta:squad` → [`RESULTS-squad.md`](docs/benchmarks/RESULTS-squad.md) |
| Test suite | **18,484 passing cases** across 1,624 test files (verified 2026-07-17) | `pnpm check` |
| Agent eval batteries | **41 live `eval:*` batteries** (tool selection, adversarial refusal, plan quality, judge meta-eval, …) | `pnpm eval:agent` and `grep -o '"eval:[a-z-]*"' package.json \| sort -u` |
| HTTP surface smoke | **51 endpoints** exercised with a key-free diagnostic provider | `pnpm smoke:broad` |
| Real-LLM round-trip | model→tool→model loop asserted end-to-end on local Ollama | `pnpm smoke:live` |
| Workspace | **37 packages + 4 apps** (CLI, API server, web console, macOS desktop), TypeScript strict | `ls packages apps` |
| Built-in tool servers | 25 in-process `muse.*` MCP servers + external stdio/SSE/streamable-HTTP | `muse mcp list` |
| Model providers | 7 families behind one `ModelProvider` seam — no vendor SDK in the core | [`packages/model`](packages/model) |

---

## ✨ Why Muse — five principles

Read these five and you know exactly what kind of agent this is.

1. **Learns how to fit into your life.**
   Facts and preferences matter, but the goal is broader: learn when to stay quiet, what
   kind of help fits, and whether it worked. The technical name for this is Attunement.
   Today Muse ships foundations for it; the complete learning loop is still a roadmap.

2. **Yours — _your personal layer can stay on your machine._**
   Muse can use a local or cloud model. With no cloud credential it falls back to the local
   Ollama model; an available cloud key may select that provider. Set `MUSE_LOCAL_ONLY=true`
   when you need a strict on

... (truncated)