# Muse Agent > An AI that stays with you between conversations. Keeps the threads you didn't finish, answers from your own notes with receipts you can open, and asks before it acts on your behalf. Provider-neutral: any model, local or cloud, your choice. - **Type:** MCP server - **Install:** `agentstack add mcp-wlsdks-muse-agent` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [wlsdks](https://agentstack.voostack.com/s/wlsdks) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [wlsdks](https://github.com/wlsdks) - **Source:** https://github.com/wlsdks/muse-agent ## Install ```sh agentstack add mcp-wlsdks-muse-agent ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Muse ### An AI that stays with you between conversations. Muse holds the threads you didn't finish, answers from your own notes with receipts you can open, and asks before it does anything on your behalf. You choose the model and where it runs. ```bash git clone https://github.com/wlsdks/muse-agent.git && cd muse-agent corepack enable && pnpm install:muse && muse onboard ``` A real session: you park a thread, and a week later Muse hands it back — with its sources. --- ### Contents | | | | --- | --- | | **Get going** | [Install](#install) · [Local or cloud](#local-or-cloud--your-choice) · [Everyday commands](#everyday-commands) | | **The idea** | [Continuity, the one thing Muse is for](#continuity--the-one-thing-muse-is-for) · [How Muse answers](#how-muse-answers) · [Where this is going](#where-this-is-going) | | **The truth** | [Status: what's real today](#status--whats-real-today) · [Evidence and numbers](#evidence-and-numbers) · [What Muse will never do](#what-muse-will-never-do) | | **The code** | [Architecture](#architecture-in-one-paragraph) · [Build and verify](#build-and-verify) · [Documentation](#documentation) | --- ## Install ### Requirements | | | | --- | --- | | **Node.js** | ≥ 22.12 (24 LTS recommended) | | **pnpm** | 10 (`corepack enable`) | | **A model** | [Ollama](https://ollama.com) on your machine, or credentials for a supported provider | | **OS** | macOS, Linux, Windows (CLI, API, recall, Ollama, opt-in PowerShell actuators) | ### Install from source ```bash git clone https://github.com/wlsdks/muse-agent.git cd muse-agent && corepack enable pnpm install:muse # frozen install → build → link the `muse` CLI → verify muse onboard ``` `pnpm install:muse` requires a clean `main`. Preview it with `pnpm install:muse -- --dry-run`, update later with `muse update`, or watch the narrated tour with `pnpm demo`. If anything looks wrong afterwards, `muse doctor` diagnoses and repairs the local setup in one pass. ### Local or cloud — your choice Supported choices include OpenAI, Anthropic, Gemini, OpenRouter, Ollama, and OpenAI-compatible endpoints. If you want a local model with no model-provider API key, point Muse at one on your own machine: ```bash brew install ollama && ollama serve & ollama pull gemma4:12b muse setup local ``` Local-only is a supported posture, not Muse's identity. Turn it on explicitly with `MUSE_LOCAL_ONLY=true` and remote model and cloud voice paths become hard errors instead of silent fallbacks. This is a scoped egress policy, not a claim that Muse audits every network path on the computer. --- ## Continuity — the one thing Muse is for Most assistants start from zero every time. Muse is built around the opposite: you tell it which thread matters, and it gives that thread back to you later — where you stopped, what changed since, the next step, and every source it used. ### 1. Start a thread and link what belongs to it ```bash muse thread start "Plan a birthday" --kind life muse thread link note birthday.md --role context muse thread link task --role next-step ``` ### 2. Get it back when you return ```bash muse continue ``` You get a **pack** — the shipped form of what the roadmap below calls the Continuity Capsule: the stopping point, the changes since, a proposed next step, and the receipts behind each claim. Nothing is guessed — the pack is built only from sources you linked. ### 3. Tell it whether that helped ```bash muse thread outcome used # or: adjusted, ignored, rejected ``` This is the loop that makes the next pack better. Outcomes are recorded, not inferred. > **Muse doesn't remember apps. It remembers the state you meant to continue.** --- ## Everyday commands | Command | What you get | | --- | --- | | `muse ask "when is the dentist?"` | An answer built from your own notes, each one cited and openable — and an honest *"I'm not sure"* when the evidence is weak. | | `muse chat` | A conversation that carries over from the last one instead of starting from zero. | | `muse today` · `muse digest` | Your day, and one evening summary instead of a stream of pings. | | `muse remember` · `muse recall` · `muse forget` | Facts, preferences, goals and vetoes you can read, correct, and delete. | | `muse notes` · `muse tasks` · `muse remind` · `muse calendar` | Plain files you own, with five calendar backends behind one interface. | | `muse proactive watch` | Muse speaks first — inside a hard interruption budget, never as an autonomous send. | | `muse mcp serve` | Other agents get read-only access to your grounded recall over MCP. | | `muse doctor` | One-shot diagnosis and repair of a broken local setup. | The same runtime drives a local web console — chat, notes, memory, continuity and the integration status, on `muse serve`: --- ## How Muse answers A personal assistant that invents a detail about your own life is worse than useless. So on the grounded paths, retrieval is not a suggestion to the model — it is a gate in front of it. | Step | What the code does | | --- | --- | | **Retrieve** | Ranks your local notes and memory for the question, across languages (a Korean question can reach an English note). | | **Weigh** | Weak matches are lowered rather than promoted. Stale sources are marked, not silently trusted. | | **Answer** | The reply must cite the sources it used. Citations that don't resolve are dropped from the answer. | | **Abstain** | Below the confidence gate, Muse says it isn't sure instead of producing a confident guess. | | **Correct** | You can contradict it. The correction is stored and decays the belief it replaced. | **The honest limit:** this covers the supported grounded paths. Fast uncited chat is a documented gap, not a solved problem — see [the grounding gate](docs/trust/grounding-gate.md). --- ## Where this is going > You stopped while comparing three places to stay. Since then the flight moved, one cancellation > deadline came close, and an 18-minute gap opened in your day. Muse prepares only the changes, > says why now, cites every source, shows exactly how far an action would go — and asks whether to > hold one option. If you answer *"this evening instead"*, that becomes a visible rule for this > trip, not a hidden global preference. Three pieces have to work for that moment to exist: | | Piece | What it decides | | --- | --- | --- | | 🌘 | **Shadow Muse** | When to speak and when to stay quiet — learned before it ever interrupts. | | 💊 | **Continuity Capsule** | The restored stopping point: changes, evidence, next step, expected time. | | 🪪 | **Policy Card** | What Muse proposes to learn about working with you — with trial, edit, reject, rollback. | None of the three is finished. The next section says exactly how far each one got. --- ## Status — what's real today ### Working | Area | Notes | | --- | --- | | Memory, grounded recall with citations, local personal stores | Optional encryption at rest for memory, episodes and the action log | | Guarded tools and browser actions, traces, checkpoints | Fail-close guards, bounded loops, timeouts | | Explicit continuity threads | `start → link → muse continue → outcome`, end to end | | One runtime across CLI, web/API, messaging, scheduled jobs | Same guards, same approvals, same traces | ### Partly built | Area | Where it actually stands | | --- | --- | | AttuneGraph engine | Exact projection, *"what changed since I stopped"*, content-addressed receipts, bounded resume compilation, canonical `.atgx`, a worker-isolated SQLite journal, an explicit opt-in Continuity Preview writer, and the offline read-only `muse attunegraph inspect` Lens — verified engine substrate; write/repair/live-web Admin and default automatic ingestion/delivery remain roadmap | | Continuity Capsule | Render data returned from an explicit API call. No product UI, no automatic timing | | Shadow Muse | The ledger records the decision. It does not surface anything on its own yet | ### Roadmap Policy Card · automatic thread detection · a durable current-world graph · standalone release of the graph engine · organic-use evidence. The fine print on the graph engine (AttuneGraph) The [AttuneGraph](docs/design/attunement/attunegraph.md) is an agent-native temporal/provenance graph and personal context compiler — not a third-party graph DB. RAG can find *likely* context; AttuneGraph has to prove the exact thread, time, change, source and policy relation. It runs on an embedded SQLite store behind an isolated worker, with no external graph server required ([blueprint](docs/design/attunement/agent-native-graph-core.md)). It is deliberately built as an independently extractable module — Muse is its first consumer and dogfood environment. The public interface, adapter boundaries and repository-split plan are fixed in [ADR 0001](docs/architecture/adr/0001-attunegraph-product-module-boundary.md); TypeScript-first with Rust only for benchmark-proven hot kernels in [ADR 0002](docs/architecture/adr/0002-attunegraph-language-runtime-boundary.md). The monorepo already enforces that boundary: `@attunegraph/core` contains the dependency-free engine, persistence, portable format, and conformance surface; `@muse/attunegraph` contains only Muse's Continuity, Shadow, Capsule, evidence, and lineage integration. What is verified today, and what those words do **not** mean: - The neutral lifecycle `openAttuneGraph({ scope, store }) → head/project → execute → close`, plus a durable projection journal and typed worker boundary. Portable export/rebuild, backup, physical forget and the 10K/100K/1M benchmarks are still pending. - `MUSE_ATTUNEGRAPH_DATABASE=/absolute/path/attunegraph.sqlite` explicitly connects the existing provider-revalidated Continuity Pack Preview path to `@muse/attunegraph/continuity-durable-projection`. It serializes writes, recovers the exact expected head after restart, treats receipt replay as idempotent, and records source freshness as `unknown`. The variable has no default; an invalid non-empty value fails assembly creation closed. - The public `@attunegraph/core/admin` Interface and `muse attunegraph inspect` Lens can inspect summary, integrity, and one exact scope head from an explicitly attested closed/quiescent store. They do not inspect a live writer, repair data, expose raw SQL, or provide the future web Admin. - Observation receipts are *caller-declared* integrity evidence. They prove bytes and boundaries — not that Muse observed you, and not your exact stopping point. - Freshness is honest by construction: only exact endpoint equality under a bounded head revalidation becomes `fresh-at-assessment`. A single read stays `unassessed` and forces downstream abstention rather than a guess. - Resume baselines are still per-process, capped at 16 threads, and not persisted. The optional AttuneGraph projection is durable but remains a rebuildable graph projection, not a durable current-world or timing claim. None of this is action authority, automatic behaviour, or evidence that it is useful in real life. Sequenced in the [wow + graph roadmap](internal/goals/attunegraph-roadmap.md). --- ## Evidence and numbers Two qualified controlled results, and nothing promoted past its evidence. Failed, unchanged and diagnostic runs stay visible in the [evidence index](docs/benchmarks/EVIDENCE.md) instead of being quietly dropped. ### Grounding For the same fictional appointment question, grounding should cite the linked note instead of answering from an assumption. Two independent controlled checks measured faithfulness: | Check | Faithfulness (gate ON vs OFF) | Delta | False-refusal cost | | --- | --- | --- | --- | | Self-authored corpus | **16/17** vs **0/17** | **+0.94** | 0/12 vs 0/12 (**+0.00**) | | SQuAD-2.0 slice | **5/8** vs **0/8** | **+0.63** | 0/8 vs 0/8 (**+0.00**) | Different denominators; deliberately not aggregated into one headline number. Source: [closed README evidence manifest](docs/benchmarks/readme-qualified-evidence-v1.json) ### Synthetic integrity at scale Four corpora — **1K / 10K / 100K / 1M** — produced **1,111,000/1,111,000** records generated, serialized, parsed and schema-validated. A separate stratified runtime sample passed **768/768** public Muse seams across **96** cells with **0 / 0 / 0** LLM, tool and network calls; owner state stayed byte-stable. Source: [canonical scale JSON](docs/benchmarks/eval-datasets-scale-v1.json) ### What these numbers do not mean - They are controlled results, not proof the agent helps in real life. The agent battery is not fully green today, and recall correction is not yet qualified — the per-battery record, including the failures, is in the [evidence index](docs/benchmarks/EVIDENCE.md). - Controlled synthetic integrity is not personal learning, and controlled evidence is not organic effectiveness. - **1,111,000 records are not 1,111,000 agent runs.** Sources: [grounding manifest](docs/benchmarks/readme-qualified-evidence-v1.json) · [scale JSON](docs/benchmarks/eval-datasets-scale-v1.json) · [evidence index](docs/benchmarks/EVIDENCE.md). --- ## What Muse will never do | | Boundary | | --- | --- | | 🚫 | **Move money.** No bank or brokerage connections, no payments, no transfers. Permanently out of scope. | | ✋ | **Send to a third party on its own.** Email, chat, forms and bookings are draft-first: you confirm the exact content and recipient, or nothing leaves. | | 🧵 | **Guess your threads.** Continuity threads and their source links are yours to author. Automatic detection is later, opt-in work. | | 👤 | **Pretend to be a workspace.** One user and one private control plane — no multi-tenancy, no RBAC. | | 📊 | **Promote evidence.** Tests, synthetic replays, diagnostics, agent trials and real outcomes stay separate ledgers. | Enforced as deterministic code, never as a prompt instruction: [outbound safety](.claude/rules/safety/outbound-safety.md) · [Attunement design](docs/design/attunement/README.md). --- ## Architecture in one paragraph `agent-core` never talks to a vendor SDK — everything goes through one `ModelProvider` interface, so swapping models does not touch agent logic. Adapters ship for OpenAI, Anthropic, Gemini, OpenRouter, Ollama and supported OpenAI-compatible endpoints (LM Studio is that adapter with a local `baseUrl`, not a dedicated one); missing capabilities degrade explicitly rather than silently. Your data stays in plain files under `~/.muse/` — plaintext by default, with memory, episodes and the action log encryptable at rest on request ([what is and is not covered](docs/trust/privacy-and-data.md)) and credentials in the OS keychain. CLI, web/API chat, messaging channels, scheduled jobs and delegated workers all share one composition root, so guards, approvals and traces are identical on every surface; risky local execution goes through the Rust `runner` as a child process. MCP works both directions — external servers behind an allowlist, and `muse mcp serve` exposing read-only grounded recall to other agents. **Full detail:** [architecture and repository layout](docs/architecture/README.md) — the provider contract, where every file lives on disk, the one-runtime rule, and a map of the 39 workspace packages. --- ## Build and verify ```bash pnpm typecheck:fast # while editing pnpm test:changed # only the tests related to your change pnpm check # full build + test, before merge pnpm lint # 0 errors required ``` Agent-level gates, which a type checker cannot replace: ```bash pnpm smoke:broad # HTTP sweep against the diagnostic provider, no API key pnpm smoke:live # real round-trip against local Ollama pnpm eval:tools # does the local model pick the right tool in one shot? pnpm eval:agent # judge meta-eval, must-refuse battery, plan quality ``` `smoke:live` deliberately uses local Ollama and skips when it is unreachable — a skip is not a pass. `eval:agent` is the nightly/ … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [wlsdks](https://github.com/wlsdks) - **Source:** [wlsdks/muse-agent](https://github.com/wlsdks/muse-agent) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-wlsdks-muse-agent - Seller: https://agentstack.voostack.com/s/wlsdks - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.